BasicDocument / SecureDoc Models

BasicDocument ("BasicDoc") / SecureDoc is a set of core information models that represents a document, including metadata and rich text.

BasicDocument is a document model that can serve as a transit data structure for document (with rich-text) conversion, such as taking input from AsciiDoc or Markdown and converting them into an output format like Metanorma StandDoc.

Its rich-text models act as a superset to the semantic elements of HTML and RTF, and therefore can fully represent the semantics of either format.

BasicDocument also provides models relating to document changes (i.e. "document/content patches"), which can be used in the case of collaborative transformation operations.

Note	BasicDocument is the document model that Selagraph operates on.

Important

The models ARE the LML files. Every model is defined in LutaML (models/*/.lml definition modules, views/.lml diagram views); the RNC files in grammars/ are implementation grammars that *accompany the LML models — never a substitute for them. This cannot be violated.

The models/ tree mirrors the metamodel’s tiers (as specified in CC/ISO 36010): document/ (with bibdata/ — the bibliographic basis, extended and implemented by relaton-models and downstream models), sections/, blocks/ (with paragraph, multi-paragraph, amend, list, table, and ancillary families), inline/ (text, id, reference, and empty element families rooted at BasicElement), change/ (the collaborative patch model), and datatypes/ (cross-cutting primitives).

This repository is the sole source of Basicdoc LML. Consumers (relaton-models, standoc-models) submodule it — do not vendor Basicdoc types elsewhere.

The Relaton Bibliography models used alongside these models live in:

• relaton/relaton-models (base grammars under relaton/grammars/)

RNG compilation of the accompanying RNC is handled by the Metanorma grammar hub (standoc-models), not by this repository.

Building

Requires Ruby, Bundler, and Graphviz (dot on PATH).

git submodule update --init --recursive
bundle install
bundle exec rake render   # regenerate images/*.png from views/*.lml
bundle exec rake verify   # assert PNG magic bytes on every committed diagram
bundle exec rake lint     # semantic lint (names, types, view closure, visibility)
bundle exec rake parity   # assert LML/RNC presence and view include graph
bundle exec rake check    # render + verify + lint + parity
bundle exec rake clean

CI runs the same build on ubuntu-latest.

Versioning

The model follows a MAJOR.MINOR.PATCH policy with a deprecation cycle and standardization snapshots — see docs/VERSIONING.md. Profiles pin the model version they target and remain valid across additive (MINOR) releases.

Model atlas (GitHub Pages)

A static site showcasing every diagram plate lives at metanorma.github.io/basicdoc-models. It is generated from views/*.lml metadata plus images/ by:

bundle exec rake site     # builds _site/ (gitignored)

The deployment workflow (.github/workflows/pages.yml) renders diagrams, runs the site generator, and publishes _site/ on every push to main. The site is a view over the LML — content is derived, never hand-authored.

Basic Document UML Models

BasicDocument

BibData

ContribMetadata

Sections

Blocks

Paragraphs

Multi-Paragraphs

Lists

Table

Ancillary Blocks

IdElements

TextElements

EmptyElements

ReferenceElements

Changes

Data Types