Contributing to MAS

April 26, 2026 · View on GitHub

Thanks for your interest in improving the Magnetic Agnostic Structure. This guide covers the mechanics of contributing. For project-level decision making, licensing and the path to standardisation, see GOVERNANCE.md.

1. Before you start

  • Read README.md, docs/schema.md and the existing schemas under schemas/ to understand the data model.
  • For anything larger than a typo or a single-field addition, open an issue first so the change can be discussed before you spend time on it.
  • For a new MAJOR change, follow the proposal process described in GOVERNANCE.md.

2. Developer Certificate of Origin (DCO)

Every commit must be signed off:

git commit -s -m "your message"

The trailer Signed-off-by: Your Name <you@example.com> certifies that you wrote the contribution (or have the right to submit it under Apache-2.0). See https://developercertificate.org for the full text.

3. Pull request checklist

  • Commits are signed off (DCO).
  • All new or modified schema files include the SPDX header "$comment": "SPDX-License-Identifier: Apache-2.0".
  • tests/ passes locally (cmake --build build && ctest).
  • Sample documents under samples/complete/ still validate.
  • If you added a field: documentation in docs/ updated, at least one example shows the field in use, and CHANGELOG.md has an entry under ## [Unreleased].
  • If the change is breaking: issue link to the accepted proposal and an entry under ### Removed or ### Changed in the changelog.

4. Schema conventions

  • JSON Schema draft 2020-12.
  • camelCase for property names.
  • Every property has a description. Every numeric property documents its unit (SI; see §5).
  • additionalProperties: false on closed objects. For vendor extensions, use the reserved vendorExtensions field (object, free-form) — do not invent new top-level fields.
  • Cross-references use relative $ref (e.g. ./utils.json#/$defs/Foo).
  • Reuse types from schemas/utils.json instead of redefining them.

5. Units and quantities

MAS uses SI units exclusively. Existing fields carry bare numbers with the unit fixed by the field's description. New numeric fields should use the Quantity pattern (value + unit) once it lands in utils.json; until then, document the unit in the description and prefer base SI (m, K, Hz, A, V, H, F, Ω, kg, s) rather than scaled units (mm, °C, MHz).

Temperature: use Kelvin for material properties; ambient-temperature fields scheduled to migrate from °C to K in a future MAJOR release.

6. Component database (data/*.ndjson)

  • One JSON object per line, no trailing comma, UTF-8.
  • Adding a material / shape / wire: include manufacturer name, datasheet URL and (when known) datasheet revision date.
  • Removing or renaming a record is a breaking change and follows the MAJOR-change process.

7. Code generation

MAS.hpp is generated by quicktype from the schemas. Do not hand-edit it. Regenerate per the instructions in BUILD.md and commit the result in the same PR as the schema change so that consumers stay in sync.

8. Reporting security or IPR concerns

Open a private issue or contact the maintainers directly; do not file a public issue for suspected patent or licensing problems.