Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions metanorma.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ metanorma:
- sources/express-pretty/document.adoc
- sources/annotated-express/document.adoc
- sources/expressdocs-migration/document.adoc
- sources/expressdocs-framework/document.adoc
- sources/express-schema-manifest/document.adoc
- sources/express-changes/document.adoc
- sources/express-mapping/document.adoc
Expand Down
57 changes: 57 additions & 0 deletions sources/expressdocs-framework/document.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
= EXPRESSdocs Publishing Framework
:docnumber: 5002
:edition: 0
:copyright-year: 2026
:revdate: 2026-11-14
:language: en
:title-main-en: EXPRESSdocs Publishing Framework
:doctype: standard
:technical-committee: EXPRESS
:imagesdir: images
:mn-document-class: elf
:mn-output-extensions: xml,html,doc,pdf,rxl
:fullname: Ronald Tse
:surname: Tse
:givenname: Ronald
:affiliation: EXPRESS Language Foundation
:fullname_2: Thomas Thurman
:surname_2: Thurman
:givenname_2: Thomas
:affiliation_2: EXPRESS Language Foundation
:docidentifier: ELF 5002 (draft)
:data-uri-image:
:local-cache-only:
:draft: 0.1

// DRAFT: number 5002 is provisional; the final document number is assigned by ELF.
// Enumerated from current practice: metanorma/annotated-express (reference
// templates), metanorma/suma (conforming engine), metanorma/mn-samples-expressdocs
// (conformance corpus), metanorma/iso-10303 (production adoption).

include::sections/00-foreword.adoc[]

include::sections/01-scope.adoc[]

include::sections/02-normrefs.adoc[]

include::sections/03-terms.adoc[]

include::sections/04-framework-overview.adoc[]

include::sections/05-project-layout.adoc[]

include::sections/06-collection-manifest.adoc[]

include::sections/07-template-contract.adoc[]

include::sections/08-anchor-reference.adoc[]

include::sections/09-urn-identity.adoc[]

include::sections/10-build-interface.adoc[]

include::sections/11-delivery-verification.adoc[]

include::sections/12-performance-contract.adoc[]

include::sections/13-conformance.adoc[]
17 changes: 17 additions & 0 deletions sources/expressdocs-framework/sections/00-foreword.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[[foreword]]
== Foreword

This document is a *working draft*. It enumerates the EXPRESSdocs publishing
framework as a contract from current practice, so that implementations other
than the originating one can conform. The normative statements in this draft
are derived from the behaviour of existing implementations, principally the
ISO 10303 (STEP) publishing pipeline; where practice diverges, this draft
states the intended contract and implementations converge towards it.

ISO/TC 184/SC 4 and other producers of Annotated EXPRESS content are users of
this framework, not its standardizers: authoring follows ELF 5001, publishing
follows this specification.

Attention is drawn to the possibility that some elements of this document may
be the subject of patent rights. ELF shall not be held responsible for
identifying any or all such patent rights.
19 changes: 19 additions & 0 deletions sources/expressdocs-framework/sections/01-scope.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
[[scope]]
== Scope

This document specifies the EXPRESSdocs publishing framework: an
implementation-neutral contract for rendering Annotated EXPRESS content into
published documentation. It defines:

* the directory layout of an EXPRESSdocs project;
* the collection manifest that declares documents and schemas to be published;
* the template contract that an implementation shall honour to render each
EXPRESS construct;
* anchor, cross-reference, and URN identity semantics;
* the build interface and its exit behaviour;
* delivery verification, provenance, and signing;
* the performance contract that implementations shall satisfy;
* conformance classes and the conformance corpus.

The *content* of Annotated EXPRESS documentation — remark types, content
syntax, and usage — is specified in ELF 5001 and is out of scope here.
14 changes: 14 additions & 0 deletions sources/expressdocs-framework/sections/02-normrefs.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
[[normrefs]]
== Normative references

The following documents are referred to in the text in such a way that some
or all of their content constitutes requirements of this document.

* *ELF 5001:2024*, _Annotated EXPRESS_ — the content specification for
annotated EXPRESS documentation (remark types, content syntax, usage).
* *ISO 10303-11*, _Industrial automation systems and integration — Product
data representation and exchange — Part 11: Description methods: The
EXPRESS language reference manual_ — the language whose schemas are the
subject of published documentation.
* *RFC 8141*, _Uniform Resource Names (URNs)_ — the syntax of the content
identifiers defined by this framework.
34 changes: 34 additions & 0 deletions sources/expressdocs-framework/sections/03-terms.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
[[terms]]
== Terms and definitions

==== EXPRESSdocs project

A directory of source material — EXPRESS schemas, Annotated EXPRESS documents
per ELF 5001, collection manifests, and authoring templates — sufficient for a
conforming implementation to produce published documentation.

==== collection manifest

A data document declaring the documents, schemas, and build directives of an
EXPRESSdocs project. It contains no executable logic.

==== implementation

A processor that consumes an EXPRESSdocs project and produces published
documentation and delivery artifacts as specified by this document.

==== derived data

Content generated by a build from source material, such as extracted concept
datasets or exported schema listings. Derived data is reproducible: it is
never an input to its own production.

==== template

An authorable rendering unit (e.g. a Liquid template) bound to one EXPRESS
construct class, through which an implementation renders that construct.

==== staged build

An implementation strategy that renders disjoint member subsets in separate
executions against a shared store, then composes the site from the store.
21 changes: 21 additions & 0 deletions sources/expressdocs-framework/sections/04-framework-overview.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
[[framework-overview]]
== Framework overview

An EXPRESSdocs project is authored once and published by any conforming
implementation:

[source]
----
schemas/ EXPRESS sources (read-only inputs)
documents/ Annotated EXPRESS documents (ELF 5001 content)
site manifest collection manifest (Clause 6)
templates/ authoring templates (Clause 7)
----
The build (Clause 10) renders the manifest through the template contract
(Clauses 7–9) into a site (Clause 11), under the performance contract
(Clause 12). Authoring is standardized at ELF 5001; this framework
standardizes everything the build does around it.

The contract is deliberately drawn so that the ISO 10303 corpus —
hundreds of schemas, thousands of documents, production CI — is a
conforming project rather than a special case.
29 changes: 29 additions & 0 deletions sources/expressdocs-framework/sections/05-project-layout.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
[[project-layout]]
== Project layout

An EXPRESSdocs project shall organize source material as follows:

[source]
----
schemas/ EXPRESS schema sources (.exp); read-only inputs
documents/<document>/ Annotated EXPRESS document sources (document.adoc,
per ELF 5001), one directory per document
<site manifest> collection manifest, Clause 6 (conventional name:
metanorma.yml)
templates/ project-level authoring templates, Clause 7
<derived>/ derived data (extracted concepts, exported schema
listings); reproducible, see below
----

Requirements:

* Schema sources shall be treated as read-only inputs. Any annotation
material an implementation synthesizes into a schema listing (e.g. figure
hotspot maps) shall be produced as *derived output at export time* from
external data, never by mutating schema sources.
* Derived data shall be reproducible from source material and build inputs.
A project may commit derived data for review, but a conforming
implementation shall regenerate it from sources and shall not consume it
as an input to its own production.
* Implementations shall write all generated output to paths derived from the
consumer's project root, never into their own installation.
28 changes: 28 additions & 0 deletions sources/expressdocs-framework/sections/06-collection-manifest.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
[[collection-manifest]]
== Collection manifest

The collection manifest is a data document (YAML) that declares what an
implementation builds. It shall contain no executable logic.

==== Structure

* *files* — the documents to render, as source paths (document.adoc entries)
or nested manifests. A document entry declares its output formats and may
declare that its rendered site is split per section (section splitting):
the split is an implementation behavior, the declaration is manifest data.
* *directives* — build directives as single-key entries. Directives are
declarative requests (e.g. `base-dir: collection` — resolve document
includes against the collection root); an implementation that does not
understand a directive shall fail loudly rather than ignore it silently.
* *collection metadata* — organization and collection name for the produced
site.

==== Requirements

* Manifest entries identify documents and schemas by path relative to the
project root; an implementation shall resolve them identically regardless
of the working directory the build is invoked from.
* Every manifest node used as a build input shall carry a stable identity so
that generated identifiers derived from it are deterministic (Clause 12).
* The manifest is the single source of document ordering; render completion
order shall never influence manifest-derived ordering.
33 changes: 33 additions & 0 deletions sources/expressdocs-framework/sections/07-template-contract.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
[[template-contract]]
== Template contract

An implementation renders each EXPRESS construct class through *authorable
templates*; the templates are part of the project, not of the implementation.

==== Template surface

The template surface shall cover at minimum: schema (identity, statements),
entity (attributes, supertypes, subtypes, where-rules), function and
procedure, rule, constant and type declarations, subtype constraint, USE
FROM and REFERENCE interfaces, ELF 5001 remarks (each remark type per its
content specification), and diagrams with hotspot maps (Clause 8).

==== Resolution order

Templates resolve from the most specific to the most general: project
templates, then flavor defaults bundled with the implementation. A project
template overrides a default of the same name; the resolution order itself
shall be deterministic.

==== Model surface

Templates receive the parsed EXPRESS model — schemas, entities, attributes,
constraints, interfaces, remarks — through a documented accessor surface.
An implementation shall document every accessor its templates rely upon;
undocumented accessors are not part of the contract and projects relying on
them do so at their own risk.

==== Compilation

An implementation shall compile authoring templates once per process and
reuse the compiled forms across documents (Clause 12, P1).
34 changes: 34 additions & 0 deletions sources/expressdocs-framework/sections/08-anchor-reference.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
[[anchor-reference]]
== Anchor and reference semantics

==== Anchors

Anchors identify linkable elements with schema-qualified identifiers, so that
cross-document references resolve globally within a project:

* schema-level elements: `[[<schema>.<element>]]`;
* attribute-level elements: `[[<schema>.<element>.<attribute>]]`;
* diagram anchors: `[[<schema>.expg<N>]]`, one per EXPRESS-G diagram in
document order.

An implementation shall emit exactly one anchor per linkable element and
shall support both the schema-qualified form and the bare form
(`[[<element>]]`), resolving the bare form within the scope of the declaring
schema.

==== Hotspot maps

Figure hotspot maps bind image regions to targets. A hotspot map is
associated with one image; each target binds a region of the image to a
cross-reference (the ELF 5001 remark syntax supplies the targets). Hotspot
binding shall be exact: a target that names a specific element binds that
element, and the binding shall survive section splitting of the rendered
site (the referenced element may render on another page; the link shall
follow it).

==== Resolution failures

A cross-reference whose target does not resolve anywhere in the project is a
verifiable diagnostic (Clause 11), not a silent drop: implementations shall
surface unresolved targets in a structured diagnostic channel, and delivery
verification counts them.
15 changes: 15 additions & 0 deletions sources/expressdocs-framework/sections/09-urn-identity.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
[[urn-identity]]
== URN identity

Published EXPRESS content carries content URNs of the form
`<base-urn>:tech:<schema>.<element>`, where `<base-urn>` is the publisher's
URN namespace for the corpus (e.g. `urn:iso:std:iso:10303:-2:ed-2:tech`).
Terminology concepts carry term URNs under the same base.

* The wildcard form `<base-urn>:tech:*` addresses the whole technical
corpus.
* URNs are stable across builds: the same schema and element yield the same
URN in every build.
* Implementations should make URNs dereferenceable: a static hosting of the
produced site shall serve each URN at a path derived from the URN itself,
negotiating between canonical data and human-readable representations.
26 changes: 26 additions & 0 deletions sources/expressdocs-framework/sections/10-build-interface.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
[[build-interface]]
== Build interface

A conforming implementation provides a build operation that consumes a
collection manifest (Clause 6) and produces the site (Clause 11).

==== Required behaviour

* The build shall resolve all document, schema, and template paths relative
to the project root, independent of the invocation working directory.
* A failing document render shall produce a non-zero build exit code and a
structured diagnostic naming the failed document; a build shall not exit
zero while an expected output is missing or a member failed.
* Incremental builds are permitted: an implementation may skip re-rendering
inputs that are unchanged, keyed by input content together with the
toolchain identity (Clause 12, P2). A cache hit shall be equivalent to a
fresh computation.

==== Permitted strategies

Staged and sharded execution — rendering disjoint member subsets in separate
executions against a shared store, then composing — is an implementation
strategy. Where used, the composition shall satisfy the same determinism and
verification requirements as a single-pass build, and a store entry shall be
consumed only when the implementation can establish what produced it
(toolchain identity; see Clause 12, P2).
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
[[delivery-verification]]
== Delivery verification

Delivery is more than a build: a produced site shall be *verified* against
declared expectations before it ships.

==== Expectations manifest

The project (or its delivery pipeline) declares an expectations manifest — a
data document stating the shape of a correct site and its diagnostic budget,
as measured values: minimum counts for site sections, index pages, schema
documents, and attachments; an exact count where the shape is fixed; an
upper bound on missing-schema pages (zero for a complete corpus); and upper
bounds on broken links and on diagnostic rows, itemized by family.

Expectations are *measured data with a trend*: caps are set to observed
values and ratchet downward as fixes land; they are never aspirational
ceilings invented to make a build pass.

==== Provenance

The build shall emit a provenance record: a canonical digest (e.g. SHA-256)
of every input and output, plus the toolchain versions. Provenance shall be
verifiable independently: recomputation from the recorded inputs either
reproduces the record or names the divergence. Signing of the provenance
record (e.g. keyless or key-based) is optional and out of scope.

==== Diagnostics channel

Unresolved cross-references, validation rows, and other diagnostics are
surfaced in a structured form and counted by *category and rule* — the
stable identity of a diagnostic — not by diagnostic code string (codes
migrate between tool releases; see Clause 13).
Loading
Loading