Architecture specification

Profiles

MatJSON is a family of interoperable working-draft profiles rather than one monolithic document. MatSpec captures intrinsic requirements; MatReq captures additional governing requirements; MatRecord normalizes evidence; MatCheck records auditable evaluations; MatJSON Core defines semantics that are genuinely shared across profiles.

Core convergence

Core v0.1 is now a published working draft, but the current MatSpecJSON v0.2.10, MatReqJSON v0.2, and MatRecordJSON v0.1 schemas remain independently valid. This avoids breaking the active libraries while the common semantics are still being proven.

Current drafts                         Next major revisions
MatSpec  v0.2.10 ─┐                    MatSpec  ─┐
MatReq   v0.2    ──┼─ shared concepts   MatReq   ─┼──→ MatJSON Core
MatRecord v0.1   ──┤   converge into    MatRecord─┤
MatCheck v0.1 ─────┘                    MatCheck ──┘

MatCheckJSON v0.1 already consumes Core v0.1 and serves as the first integration proving ground. In the next profile revisions, only primitives with identical semantics should be moved to Core; profile-specific rules remain in their owning schema.

Effective requirements stack

MatSpecJSON
    + invoked MatReqJSON documents
    + direct material requisition requirements
    = effective material requirements

The material requisition remains the project-specific source of truth. MatJSON does not currently define a separate MatCtx profile.

Invocation

A requisition can invoke an entire standard, a section, a clause, an annex, or a direct purchaser-defined requirement. Informative or example content can be contractually elevated when the purchaser explicitly invokes it using mandatory language.

Material must meet NACE MR0175.
Material must meet API TR 938-C Appendix A.
Carbon steel must comply with API 663 Section 8.2.
Maximum carbon equivalent must be 0.43.

Reference-only language such as “see” or “for guidance” must not silently import an entire document.

Normative language

MatJSON-authored requirements use must and must not for mandatory behavior. Recommended behavior uses should, and optional behavior uses may. Source-document modal wording is preserved separately as provenance when needed.

Versioning

MatJSON separates the profile/schema version from the edition of the source engineering document. These are independent dimensions.

{
  "matjson": { "profile": "matreq", "version": "0.2" },
  "document": {
    "organization": "Example",
    "designation": "SMR-10",
    "edition": { "publication": "2026-08" }
  }
}

Canonical identifiers

Stable URIs should identify documents, grades, rules, calculations, and controlled terms. The URI can resolve to public metadata without reproducing copyrighted source text.

https://matjson.org/id/document/api/663/2022
https://matjson.org/id/rule/api/663/2022/8.2.2

Conformance

1. Syntactically conforming
2. Semantically conforming
3. Source-complete
4. Technically reviewed
5. Verified publication

JSON Schema validation establishes only the first level.

Extensions

Domain-specific extensions should use URI namespaces. A reader should preserve unknown extensions but must not infer that they alter core requirements.

{
  "extensions": {
    "https://example-aircraft.org/matjson": {
      "fatigue_classification": "A3"
    }
  }
}

Publication boundary