BC Observatoryunofficial, made by waldo
code change · featureIntegration & APIsofficial - Microsoftreviewed - checked by Opus

#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.

Open in Claude149.mdPull request #149

Pull request · 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).