---
id: change/bcquality/149
type: change
title: "#149 knowledge(web-services): under schema 2.0 an API enum field is a contract by member name, under 1.0 by caption"
summary: "A knowledge article clarifies how API enum fields are published: under schema 2.0 by member name with captions in entityDefinitions, under schema 1.0 by en-US caption as Edm.String. Good and bad code samples demonstrate the contract implications."
tier: official
language: en
tags:
  - feature
  - main
system: integration
review:
  state: reviewed
  by: opus
  at: "2026-10-08T02:06:32.163Z"
  flags: []
generated:
  at: "2026-10-08T01:26:53.141Z"
  pipeline: 0.2.0
  prompts:
    extract-change: 1
  input_hash: 2439d5c41243705d91e1a5e194abdcb142eb946d
evidence:
  - kind: code
    url: https://github.com/microsoft/BCQuality/pull/149
    title: "microsoft/BCQuality#149: knowledge(web-services): under schema 2.0 an API enum field is a contract by member name, under 1.0 by caption"
    date: "2026-09-02"
    commit: 2439d5c41243705d91e1a5e194abdcb142eb946d
    t: null
    quote: null
links:
  learn: []
  objects: []
  features: []
  topics: []
  localizations: []
  videos: []
  posts: []
  guidelines: []
  changes: []
number: 149
repo: microsoft/BCQuality
source_id: bcquality-prs
url: https://github.com/microsoft/BCQuality/pull/149
kind: pr
base_branch: main
major: null
merged_at: "2026-09-02T14:26:25Z"
author: waldo1001
author_type: User
community_contribution: false
labels: []
change_class: code
change_kind: feature
behavior_change: false
breaking: false
files:
  count: 3
  additions: 150
  deletions: 0
  al: 3
apps: []
objects_touched: []
objects_unjoined:
  - path: community/knowledge/web-services/api-enum-values-are-a-contract-by-name-not-ordinal.bad.al
    status: added
    reason: not-in-snapshot
  - path: community/knowledge/web-services/api-enum-values-are-a-contract-by-name-not-ordinal.good.al
    status: added
    reason: not-in-snapshot
  - path: community/knowledge/web-services/api-enum-values-are-a-contract-by-name-not-ordinal.md
    status: added
    reason: not-in-snapshot
obsoletions: []
backports: []
fixes_issues: []
work_items: []
systems:
  - integration
  - development
quote: null
joined_against:
  major: null
  commit: null
---

# #149 knowledge(web-services): under schema 2.0 an API enum field is a contract by member name, under 1.0 by caption

> A knowledge article clarifies how API enum fields are published: under schema 2.0 by member name with captions in entityDefinitions, under schema 1.0 by en-US caption as Edm.String. Good and bad code samples demonstrate the contract implications.

[Pull request](https://github.com/microsoft/BCQuality/pull/149) · merged into `main` on 2026-09-02 by waldo1001 · 3 files (+150 -0), 3 AL · feature · tier official · reviewed (checked by Opus)

## What changed

- Schema version determines how enum fields are published in custom APIs, not the ordinal
- Schema 2.0 (BC 24 default) uses strongly typed enums with member names in metadata and responses
- Schema 1.0 (legacy) uses Edm.String with en-US captions in responses
- Renaming enum members breaks schema 2.0 APIs even if captions remain unchanged
- Virtual tables match by External Name, a separate mechanism from API schema contracts

## AL objects touched

- `community/knowledge/web-services/api-enum-values-are-a-contract-by-name-not-ordinal.bad.al`: added, not in the BC? snapshot yet
- `community/knowledge/web-services/api-enum-values-are-a-contract-by-name-not-ordinal.good.al`: added, not in the BC? snapshot yet
- `community/knowledge/web-services/api-enum-values-are-a-contract-by-name-not-ordinal.md`: added, not in the BC? snapshot yet

## Context

- Systems: integration, development

Source: metadata of a merged pull request in microsoft/BCQuality (bcquality): title, labels, changed paths and counts, with a summary in our words. No source text and no description beyond one short quote (D10, D61).