Skip to content

Commit 2e8da49

Browse files
ronaldtseronaldtse
committed
feat: migrate express-change and express-schema-manifest from individual repos
1 parent e29cd95 commit 2e8da49

20 files changed

Lines changed: 711 additions & 0 deletions

‎README.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ The specifications include:
1818

1919
5001:: *Annotated EXPRESS* -- Specification for documenting EXPRESS models with structured annotations
2020
5002:: *EXPRESS language pretty print format* -- Specification for standardized formatting of EXPRESS language constructs
21+
5003:: *EXPRESS documentation migration* -- Specification for migrating EXPRESS documentation to the new format
22+
5004:: *EXPRESS schema manifest* -- Specification for creating a manifest of EXPRESS schemas
23+
5005:: *EXPRESS changes* -- Specification for documenting changes to the EXPRESS language and its specifications
2124

2225
These specifications are written in Metanorma to generate standardized
2326
documentation in multiple formats.
@@ -35,6 +38,12 @@ EXPRESS language pretty print format specification
3538
`sources/expressdocs-migration/`:::
3639
Migration of EXPRESS documentation to EXPRESSdocs
3740

41+
`sources/express-schema-manifest/`:::
42+
EXPRESS schema manifest specification
43+
44+
`sources/express-changes/`:::
45+
EXPRESS changes specification
46+
3847
== Building documentation
3948

4049
This repository uses Metanorma to build standardized documentation.

‎metanorma.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ metanorma:
55
- sources/express-pretty/document.adoc
66
- sources/annotated-express/document.adoc
77
- sources/expressdocs-migration/document.adoc
8+
- sources/express-schema-manifest/document.adoc
9+
- sources/express-changes/document.adoc
810

911
collection:
1012
organization: "EXPRESS Language Foundation"

‎sources/express-changes/document.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
= EXPRESS changes model (in YAML)
2+
:docnumber: 5005
3+
:edition: 1
4+
:copyright-year: 2025
5+
:revdate: 2025-02-06
6+
:language: en
7+
:title-main-en: EXPRESS changes model in YAML
8+
:doctype: international-standard
9+
:technical-committee: EXPRESS
10+
:imagesdir: images
11+
:mn-document-class: iso
12+
:mn-output-extensions: xml,html,doc,pdf,rxl
13+
:fullname: Ronald Tse
14+
:surname: Tse
15+
:givenname: Ronald
16+
:affiliation: EXPRESS Language Foundation
17+
:fullname_2: Thomas Thurman
18+
:surname_2: Thurman
19+
:givenname_2: Thomas
20+
:affiliation_2: EXPRESS Language Foundation
21+
:publisher: ELF
22+
:data-uri-image:
23+
:local-cache-only:
24+
25+
include::sections/00-foreword.adoc[]
26+
27+
include::sections/00-introduction.adoc[]
28+
29+
include::sections/01-scope.adoc[]
30+
31+
include::sections/02-normrefs.adoc[]
32+
33+
include::sections/03-terms.adoc[]
34+
35+
include::sections/04-spec.adoc[]
36+
37+
include::sections/az-bibliography.adoc[]

‎sources/express-changes/sections/00-foreword.adoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.Foreword
2+
The EXPRESS Language Foundation ("`ELF`") is a registered public charity in the
3+
US that facilitates the education, standardization, research, promotion,
4+
definition, and usage of information modelling and programming languages, with a
5+
focus on the EXPRESS language family.
6+
7+
ELF works with international partners and experts across the globe, reflecting
8+
the international nature of its mission. More information about ELF is available
9+
on the official website (https://www.expresslang.org).
10+
11+
The procedures used to develop this document and those intended for its further
12+
maintenance are described in the ELF Directives.
13+
14+
In particular, the different approval criteria needed for the different types of
15+
ELF documents should be noted. This document was drafted in accordance with the
16+
editorial rules of the ELF Directives.
17+
18+
Attention is drawn to the possibility that some of the elements of this document
19+
may be the subject of patent rights. ELF shall not be held responsible for
20+
identifying any or all such patent rights. Details of any patent rights
21+
identified during the development of the document will be provided in the
22+
Introduction.
23+
24+
Any trade name used in this document is information given for the convenience of
25+
users and does not constitute an endorsement.
26+
27+
This document was prepared by Technical Committee _{technical-committee}_.

‎sources/express-changes/sections/00-introduction.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
2+
== Introduction
3+
4+
This document specifies the YAML format used to track changes in EXPRESS schema
5+
files.

‎sources/express-changes/sections/01-scope.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
2+
== Scope
3+
4+
This document specifies the YAML format used to track changes in EXPRESS schema
5+
files.

‎sources/express-changes/sections/02-normrefs.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
2+
[bibliography]
3+
== Normative references
4+
5+
* [[[ISO10303-1,ISO 10303-1:2024]]]
6+
7+
* [[[ISO10303-11,ISO 10303-11:2004]]]

‎sources/express-changes/sections/03-terms.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
2+
== Terms and definitions
3+
4+
=== change
5+
6+
modification to an EXPRESS schema that alters the structure or semantics of the
7+
schema

‎sources/express-changes/sections/04-spec.adoc‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
== Format structure
2+
3+
The EXPRESS Changes YAML format follows this basic structure:
4+
5+
[source,yaml]
6+
----
7+
path: String (required)
8+
# Relative path to the EXPRESS file
9+
changes:
10+
- type: String (required)
11+
# Type of change: add, remove, modify
12+
entity: String (required)
13+
# Name of the entity being changed
14+
details: String (required)
15+
# Description of the change
16+
original: String (optional)
17+
# Original content (for modify/remove)
18+
new: String (optional)
19+
# New content (for add/modify)
20+
----
21+
22+
== Change types
23+
24+
=== Add
25+
26+
Used when adding new elements to the schema.
27+
28+
.Example
29+
[example]
30+
====
31+
[source,yaml]
32+
----
33+
path: data/schema.exp
34+
changes:
35+
- type: add
36+
entity: PERSON
37+
details: Add new entity for representing individuals
38+
new: |
39+
ENTITY PERSON;
40+
name: STRING;
41+
age: INTEGER;
42+
END_ENTITY;
43+
----
44+
====
45+
46+
=== Remove
47+
48+
Used when removing elements from the schema.
49+
50+
.Example
51+
[example]
52+
====
53+
[source,yaml]
54+
----
55+
path: data/schema.exp
56+
changes:
57+
- type: remove
58+
entity: OBSOLETE_TYPE
59+
details: Remove deprecated type definition
60+
original: |
61+
TYPE OBSOLETE_TYPE = INTEGER;
62+
END_TYPE;
63+
----
64+
====
65+
66+
=== Modify
67+
68+
Used when modifying existing elements.
69+
70+
.Example
71+
[example]
72+
====
73+
[source,yaml]
74+
----
75+
path: data/schema.exp
76+
changes:
77+
- type: modify
78+
entity: PERSON
79+
details: Add email attribute to PERSON entity
80+
original: |
81+
ENTITY PERSON;
82+
name: STRING;
83+
END_ENTITY;
84+
new: |
85+
ENTITY PERSON;
86+
name: STRING;
87+
email: STRING;
88+
END_ENTITY;
89+
----
90+
====
91+
92+
== Validation rules
93+
94+
1. The `path` field must be a valid relative path to an EXPRESS file
95+
2. Each change must have a `type`, `entity`, and `details` field
96+
3. `original` is required for `remove` and `modify` types
97+
4. `new` is required for `add` and `modify` types
98+
5. Multiple changes can be specified for the same file
99+
100+
== Usage guidelines
101+
102+
1. Keep change descriptions clear and specific
103+
2. Include context in the details field
104+
3. Maintain proper EXPRESS syntax in original/new content
105+
4. Use consistent indentation in YAML structure

‎sources/express-changes/sections/aa-example.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[appendix,obligation=informative]
2+
== Changes YAML example
3+
4+
This annex provides an example of the EXPRESS Changes YAML format.
5+
6+
TODO.
7+

0 commit comments

Comments
 (0)