Document mapping documents as the only shape; embedded mappings deprecated

Lead the Mapping documents section with the standalone mapping document and
reduce the embedded ontology_mappings shape to a short deprecation note, so
embedding no longer reads as a reasonable alternative. Align the field table,
version history, and ontology.json description with the same wording.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PEsT5t9mcXM6fF4QUC8Y7V

Author: Shao Xie

ontology/ontology.json

@@ -38,7 +38,7 @@
     },
     "ontology_mappings": {
       "type": "array",
-      "description": "Collection of ontology maps from logical models, each embedding its own semantic model. Kept for backward compatibility; see ontology/mapping.json for the standalone mapping document, the recommended shape when more than one semantic model maps to this ontology.",
+      "description": "Deprecated. Embedded ontology maps, accepted only so existing documents continue to validate; write mappings as standalone documents validated against ontology/mapping.json instead.",
       "deprecated": true,
       "items": {
         "$ref": "#/$defs/OntologyMap"

ontology/ontology.md

@@ -88,7 +88,7 @@ hierarchically, grouping each relationship under the concept that plays its firs
 | `description` | string | No | Human-readable description |
 | `ai_context` | string/object | No | Additional context for AI tools |
 | `ontology` | list | Yes | Concepts and relationships they group that form this ontology |
-| `ontology_mappings` | list | No | Embedded ontology maps (legacy shape, kept for backward compatibility); see [Mapping documents](#mapping-documents) for the standalone alternative |
+| `ontology_mappings` | list | No | Deprecated; accepted only so existing documents continue to validate. Write mappings as [mapping documents](#mapping-documents) instead |
 
 Each component of an ontology declares a concept and lists the relationships where that
 concept plays the first role. The concept's name is the value of the `concept` field, and
@@ -388,28 +388,9 @@ mappings that group by some concept.
 
 ### Mapping documents
 
-An ontology mapping can be expressed two ways. It can be embedded inside the ontology document
-itself, as an entry in the top-level `ontology_mappings` list; this is the original shape and
-remains valid for backward compatibility. Each entry has the following schema, mirroring
-`OntologyMap` in `ontology.json`:
-
-| Field | Type | Required | Description |
-|---------------|---------|-----|-------|
-| `name` | string | No | Name of this ontology map |
-| `description` | string | No | Human-readable description of this ontology map |
-| `semantic_model` | object | Yes | A complete, embedded semantic model document (see the core specification) |
-| `concept_mappings` | list | Yes | Maps logical model constructs to concepts and relationships in this ontology |
-
-Embedding a full semantic model inside the ontology document works cleanly when exactly one
-semantic model maps to the ontology. It does not compose: if a second team wants to bring a second
-semantic model to the same ontology, the natural next step is another entry in the same
-`ontology_mappings` list, which means duplicating the embedded model or coordinating changes
-through a file the second team does not otherwise own.
-
-Alternatively, and the recommended approach when more than one semantic model maps to an ontology,
-or when the mapping is owned by a different team than the ontology itself, a mapping can be written
-as its own standalone document, validated against `ontology/mapping.json`. Instead of embedding a
-semantic model, it references both the ontology and the semantic model it maps between:
+A mapping is written as its own document, validated against `ontology/mapping.json`. It maps the
+constructs of one semantic model onto one ontology, and references both rather than embedding
+either:
 
 | Field | Type | Required | Description |
 |---------------|---------|-----|-------|
@@ -421,27 +402,24 @@ semantic model, it references both the ontology and the semantic model it maps b
 | `concept_mappings` | list | Yes | Maps logical model constructs to concepts and relationships in the referenced ontology |
 | `custom_extensions` | list | No | Vendor-specific attributes for extensibility, matching the core specification's mechanism |
 
-Both `ontology` and `semantic_model` are references, not embedded documents. A reference is an
-object with a `name`, which must equal the referenced document's own `name` and carries this
-reference's checkable identity, and an `iri`, which says where to resolve it from: a relative
-reference such as `./flights.ontology.yaml` when the two documents sit alongside each other, or an
-absolute IRI once a catalog resolves names to locations.
+A reference is an object with a `name`, which must equal the referenced document's own `name`, and
+an `iri`, which says where to resolve it from: a relative reference such as
+`./flights.ontology.yaml` when the documents sit alongside each other, or an absolute IRI once a
+catalog resolves names to locations.
 
-A mapping document references exactly one ontology and exactly one semantic model. When an
-ontology has more than one semantic model mapped to it, each mapping is its own document; nothing
-in this specification lets a single mapping document reference two semantic models at once, so
-there is no need for `concept_mappings` expressions to disambiguate which semantic model a dataset
-belongs to.
+A mapping document references exactly one ontology and exactly one semantic model. When more than
+one semantic model maps to an ontology, each mapping is its own document.
 
 A mapping document is recognized by having `concept_mappings`, a field no ontology or semantic
-model document has; there is no separate field declaring which of the three document kinds a given
-file is. Tooling that needs to know a document's kind ahead of validating it, as
-`validation/validate.py`'s `--schema` flag does today, still needs to be told explicitly, the same
-as it does today for the two existing document kinds.
+model document has; there is no separate field declaring a document's kind.
 
 See `examples/flights.ontology.yaml`, `examples/flights.semantic_model.yaml`, and
-`examples/flights.mapping.yaml` for the canonical `flights.yaml` example split into its three
-parts.
+`examples/flights.mapping.yaml` for a complete example.
+
+**Deprecated:** mappings were originally embedded, each with a full copy of its semantic model,
+in the ontology document's `ontology_mappings` list (`OntologyMap` in `ontology.json`). That list
+is still accepted so existing documents continue to validate, but it is deprecated and will be
+removed in a future version. New mappings must be written as mapping documents.
 
 ### Concept mappings
 
@@ -648,9 +626,8 @@ though `Store` plays a role in three of the relationships.
 - **0.2.0.dev0** (2026-05-29): Basic support for ontologies and logical schema mappings
   - Core ontology structure: Concepts, relationships, and business rules (requires and derived_by)
   - Schema mappings from one or more logical models into an ontology
-  - Standalone mapping documents (`ontology/mapping.json`) as an alternative to embedding a
-    semantic model inside `ontology_mappings`, for ontologies mapped to more than one semantic
-    model or mappings owned by a different team than the ontology
+  - Mapping documents (`ontology/mapping.json`) that reference one ontology and one semantic
+    model; embedded `ontology_mappings` is deprecated
 
 ---