Update schema manifest document

.gitignore

@@ -2,6 +2,13 @@
 Gemfile.lock
 *.log.*
 *.err
+*.err.*
 relaton/
 iev/
 _site/
+document.xml
+document.pdf
+document.html
+document.rxl
+document.presentation.xml
+document.doc

sources/express-changes/examples/arm.changes.yaml

@@ -1,6 +1,6 @@
 # yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
 ---
 schema: Document_and_version_identification_arm
-editions:
-- version: '2'
-- version: '3'
+versions:
+- version: 2
+- version: 3

sources/express-changes/examples/mapping.changes.yaml

@@ -1,17 +1,17 @@
 # yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/mapping_changes.yaml
 ---
 schema: dimension_tolerance
-editions:
-- version: '6'
+versions:
+- version: 6
   mappings:
   - description: Geometric_dimension entity and attributes mapping has been updated
   - description: Angle_plus_minus_bounds and Length_plus_minus_bounds mappings was
       added
-- version: '7'
+- version: 7
   mappings:
   - description: Angle_plus_minus_bounds mapping has been updated
   - description: Length_plus_minus_bounds mapping has been updated
   - description: Applied_activity_assignment ENTITY mapped
-- version: '8'
+- version: 8
   mappings:
   - description: Geometric_dimension entity and attributes mapping has been updated

sources/express-changes/examples/mim.changes.yaml

@@ -1,12 +1,12 @@
 # yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
 ---
 schema: Document_and_version_identification_mim
-editions:
-- version: '2'
+versions:
+- version: 2
   deletions:
   - type: USE_FROM
     name: Product_identification_mim
-- version: '3'
+- version: 3
   additions:
   - type: USE_FROM
     name: product_definition_schema

sources/express-changes/examples/support_resource_schema.changes.yaml

@@ -1,8 +1,8 @@
 # yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
 ---
 schema: support_resource_schema
-editions:
-- version: '2'
+versions:
+- version: 2
   description: |-
     The definitions of the following EXPRESS entity data types were modified:
 
@@ -15,7 +15,7 @@ editions:
   modifications:
   - type: FUNCTION
     name: bag_to_set
-- version: '4'
+- version: 4
   description: |-
     The following entity types had been introduced to support external element references outside the local population of entity instances:
 

sources/express-changes/schemas/schema_changes.yaml

@@ -41,9 +41,9 @@ definitions:
         description: Array of modified elements
         items:
           $ref: '#/definitions/item_change'
-      removals:
+      deletions:
         type: array
-        description: Array of removed elements
+        description: Array of deleted elements
         items:
           $ref: '#/definitions/item_change'
   item_change:

sources/express-changes/sections/aa-examples.adoc

@@ -3,7 +3,7 @@
 
 === General
 
-This annex provides example of the EXPRESS Changes YAML format.
+This annex provides examples of the EXPRESS Changes YAML format.
 
 === Schema change
 

sources/express-changes/sections/ab-schemas.adoc

@@ -3,32 +3,49 @@
 
 === General
 
-This annex provides the JSON Schema definitions for the EXPRESS Changes YAML
+This annex provides the YAML Schema definitions for the EXPRESS Changes YAML
 formats defined in this document.
 
 These schemas can be used to validate EXPRESS Changes YAML files and to
 generate documentation or tooling for working with EXPRESS change records.
 
+The schemas are defined in YAML Schema format that follows the JSON Schema
+format (draft-07).
+
+
 === Schema change schema
 
 The schema change schema defines the structure for recording modifications to
 EXPRESS schema structure across versions, as described in <<schema-change>>.
 
-The schema is defined in JSON Schema format (draft-07).
-
 [source,yaml]
 ----
 include::../schemas/schema_changes.yaml[]
 ----
 
+This schema can be used for validation by prefixing an EXPRESS Changes YAML
+file with the following comment line:
+
+[source,yaml]
+----
+# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
+----
+
 === Mapping change schema
 
 The mapping change schema defines the structure for recording modifications to
 EXPRESS schema mappings across versions, as described in <<mapping-change>>.
 
-The schema is defined in JSON Schema format (draft-07).
-
 [source,yaml]
 ----
 include::../schemas/mapping_changes.yaml[]
 ----
+
+This schema can be used for validation by prefixing an EXPRESS Changes YAML
+file with the following comment line:
+
+[source,yaml]
+----
+# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/mapping_changes.yaml
+----
+

sources/express-schema-manifest/document.adoc

@@ -34,4 +34,8 @@ include::sections/03-terms.adoc[]
 
 include::sections/04-syntax.adoc[]
 
+include::sections/aa-examples.adoc[]
+
+include::sections/ab-schemas.adoc[]
+
 include::sections/99-bibliography.adoc[]

sources/express-schema-manifest/schemas-srl.yml → sources/express-schema-manifest/examples/schemas-srl.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://www.expresslang.org/schemas/manifest/v1/schema_manifest.yaml
 ---
 schemas:
   action_and_model_relationships_schema:

sources/express-schema-manifest/schemas/schema_manifest.yaml

@@ -0,0 +1,36 @@
+$schema: http://json-schema.org/draft-07/schema#
+title: EXPRESS Schema Manifest
+description: Defines a cohesive set of EXPRESS schemas and their locations.
+type: object
+required:
+  - schemas
+additionalProperties: false
+properties:
+  path:
+    type: string
+    description: >-
+      (optional) Root path for all schemas. If not set, the root path is set to
+      the directory where the manifest file is located. Can be an absolute path
+      or include shell expansions like ~ for home directory.
+  schemas:
+    type: object
+    description: >-
+      Map of schema names to their configurations. Each key is the name
+      of an EXPRESS schema.
+    additionalProperties:
+      oneOf:
+        - type: "null"
+          description: >-
+            Schema uses default path pattern: `{root_path}/{schema_name}.exp`.
+        - type: object
+          description: >-
+            Schema configuration with explicit path.
+          additionalProperties: false
+          properties:
+            path:
+              type: string
+              description: >-
+                Path to the schema file, relative to root path or absolute.
+                Relative paths that do not start with `/` are considered relative
+                to the root path. `..` can be used to refer to parent directories.
+                Can include shell expansions like `~`.

sources/express-schema-manifest/sections/04-syntax.adoc

@@ -1,3 +1,4 @@
+[[syntax]]
 == Syntax
 
 === General
@@ -28,7 +29,7 @@ schemas: <2>
   # ...
 ----
 <1> (optional) Root path
-<2> (mandatory)Schema listings
+<2> (mandatory) Schema listings
 <3> (mandatory) Individual EXPRESS schema names
 <4> (optional) Individual schema path
 

sources/express-schema-manifest/sections/aa-examples.adoc

@@ -0,0 +1,12 @@
+[appendix,obligation=informative]
+== Examples
+
+This annex provides examples of the EXPRESS Schema Manifest format.
+
+This example shows a schema manifest that defines a selection of schemas from
+the SRL (STEP Resource Library).
+
+[source,yaml]
+----
+include::../examples/schemas-srl.yaml[]
+----

sources/express-schema-manifest/sections/ab-schemas.adoc

@@ -0,0 +1,41 @@
+[appendix,obligation=normative]
+== Schemas
+
+=== General
+
+This annex provides the YAML Schema definitions for the EXPRESS Schema Manifest YAML
+format defined in this document.
+
+This schema can be used to validate EXPRESS Schema Manifest YAML files and to
+generate documentation or tooling for working with EXPRESS change records.
+
+The schemas are defined in YAML Schema format that follows the JSON Schema
+format (draft-07).
+
+The schema change schema defines the structure for recording modifications to
+EXPRESS schema structure across versions, as described in <<syntax>>.
+
+[source,yaml]
+----
+include::../schemas/schema_manifest.yaml[]
+----
+
+This schema can be used for validation by prefixing an EXPRESS Schema Manifest
+YAML file with the following comment line:
+
+[source,yaml]
+----
+# yaml-language-server: $schema=https://www.expresslang.org/schemas/manifest/v1/schema_manifest.yaml
+----
+
+[example]
+====
+[source,yaml]
+----
+# yaml-language-server: $schema=https://www.expresslang.org/schemas/manifest/v1/schema_manifest.yaml
+---
+schemas:
+  action_schema:
+    path: ./schemas/action_schema.exp
+----
+====