metaschema-module-authoring

Metaschema Module Authoring

This skill guides the creation and modification of Metaschema modules, which define information models that can be serialized to XML, JSON, or YAML.

Repository-specific conventions (file locations, namespaces, testing) are in .claude/rules/metaschema-authoring.md.

Module Authoring Formats

Metaschema modules can be authored in either XML or YAML format. These formats are semantically equivalent:

• Both produce identical module definitions
• Both enable parsing and serialization of data in all three formats (XML, JSON, YAML)
• The choice of authoring format does not limit the data formats the module can handle

For example, a module written in YAML can parse XML documents and serialize to JSON, and vice versa. The authoring format is purely a developer preference.

Module Structure

YAML Format

---
METASCHEMA:
  schema-name: Human-readable module name
  short-name: module-short-name
  namespace: http://example.com/ns/module
  json-base-uri: http://example.com/ns/module
  schema-version: 1.0.0
  definitions:
  - object-type: assembly
    name: root-assembly
    # ... definition content

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0">
  <schema-name>Human-readable module name</schema-name>
  <schema-version>1.0.0</schema-version>
  <short-name>module-short-name</short-name>
  <namespace>http://example.com/ns/module</namespace>
  <json-base-uri>http://example.com/ns/module</json-base-uri>

  <define-assembly name="root-assembly">
    <!-- definition content -->
  </define-assembly>
</METASCHEMA>

Required Header Elements

Element	Description
schema-name	Human-readable module name for documentation
schema-version	Semantic version (e.g., 1.0.0)
short-name	Unique identifier, used in artifact names
namespace	XML namespace URI for elements
json-base-uri	URI for JSON Schema $schema keyword