ARDS Developer Guide — Quickstart, Validator & Examples

Quickstart — Five Minutes to Conformance

Get ards-validate

The official ARDS validator is a single Python 3 file with no dependencies. Download and run it anywhere Python is available.

# Download
curl -O https://tools.axiomordo.com/ards-validate/ards_validate.py

# Or clone the repo
git clone https://github.com/axiomordo/ards-validate.git

Create Your First Artefact

Every ARDS artefact starts with the ards:meta envelope. Save the example below as my-artefact.json.

Validate It

python3 ards_validate.py my-artefact.json --level core-conformant

A passing result looks like this:

ARDS Validator v1.0.0
File: my-artefact.json

✓  CONFORMANT at level: core-conformant
   Artefact Type : RegulatoryObligationRecord
   Artefact ID   : urn:uuid:3f8e4a21-7c1b-4d09-9e12-a5b6c7d8e901
   ARDS Version  : 1.0.0
   Errors        : 0
   Warnings      : 0

ards-validate CLI Reference

The official ARDS validator. Pure Python 3. No dependencies. Validates artefacts against any conformance level.

Usage

python3 ards_validate.py <file> [options]
python3 ards_validate.py --batch <directory> [options]

Options:
  --level    schema-valid | core-conformant | extended-conformant
             Default: core-conformant
  --output   human | json | summary
             Default: human
  --strict   Treat warnings as errors
  --quiet    Suppress output; use exit code only
  --version  Print version and exit
  --help     Show help

Exit Codes

Code	Meaning
`0`	Artefact is conformant at the specified level
`1`	Artefact is non-conformant (one or more errors)
`2`	Validator error (file not found, invalid JSON, etc.)

JSON Output Mode

python3 ards_validate.py artefact.json --output json | jq .

{
  "file": "artefact.json",
  "conformant": true,
  "level": "core-conformant",
  "artefactType": "RegulatoryObligationRecord",
  "artefactId": "urn:uuid:3f8e4a21-7c1b-4d09-9e12-a5b6c7d8e901",
  "ardsVersion": "1.0.0",
  "errors": [],
  "warnings": []
}

Batch Mode

# Validate every .json file in a directory
python3 ards_validate.py --batch ./artefacts/ --output summary

File                          Level           Result    Errors  Warnings
---                           ---             ---       ---     ---
obligation-record.json        core-conformant PASS      0       0
evidence-artefact.json        core-conformant PASS      0       1
compliance-verdict.json       core-conformant PASS      0       0
invalid-missing-fields.json   core-conformant FAIL      14      0

Summary: 3 passed / 1 failed / 0 errors

CI/CD Integration

# GitHub Actions example
- name: Validate ARDS artefacts
  run: |
    python3 ards_validate.py --batch ./compliance-outputs/ \
      --level core-conformant \
      --output json \
      --strict

Error Code Reference

Every validation error carries a structured code. Use these to implement targeted fixes in your producer logic.

Code	Severity	Description
`ARDS-001`	Error	Input is not a JSON object
`ARDS-002`	Error	Missing required top-level key `ards:meta`
`ARDS-010`	Error	Required field missing from `ards:meta`
`ARDS-011`	Error	Invalid `ardsVersion` — must be SemVer format
`ARDS-013`	Error	Invalid `schemaVersion` — must be SemVer format
`ARDS-014`	Error	Invalid `artefactType` — not a recognised enum value
`ARDS-015`	Error	Invalid `artefactId` — must be `urn:uuid:{uuid-v4}`
`ARDS-016`	Error	Invalid `producedAt` — must be ISO 8601 with timezone
`ARDS-030`	Error	Missing `producerIdentity.system`
`ARDS-031`	Error	Missing `producerIdentity.organisation`
`ARDS-040`	Error	Missing `regulatoryContext.regulation`
`ARDS-041`	Error	Missing `regulatoryContext.regulatoryBody`
`ARDS-042`	Error	Missing `regulatoryContext.jurisdiction`
`ARDS-043`	Error	Missing `regulatoryContext.applicablePeriod`
`ARDS-044`	Error	Missing `applicablePeriod.startDate`
`ARDS-045`	Error	Missing `applicablePeriod.endDate`
`ARDS-046`	Error	`startDate` is after `endDate`
`ARDS-W011`	Warning	`ardsVersion` is not the current stable version (1.0.0)
`ARDS-W030`	Warning	`producerIdentity.systemVersion` not present (SHOULD)
`ARDS-W600`	Warning	`certificationId` not present — cannot verify producer certification

Example Artefacts

Reference implementations for all six artefact types. All examples pass ards-validate --level core-conformant.

Regulatory Obligation Record (FuelEU)

{
  "ards:meta": {
    "ardsVersion": "1.0.0",
    "schemaId": "https://schema.axiomordo.com/ards/1.0/fueleu/obligation-record.schema.json",
    "schemaVersion": "1.0.0",
    "artefactType": "RegulatoryObligationRecord",
    "artefactId": "urn:uuid:3f8e4a21-7c1b-4d09-9e12-a5b6c7d8e901",
    "producedAt": "2026-05-15T09:00:00Z",
    "producerIdentity": {
      "system": "ShipCompliance Pro",
      "systemVersion": "3.1.0",
      "organisation": "Nordic Maritime GmbH"
    },
    "regulatoryContext": {
      "regulation": "FuelEU Maritime",
      "regulatoryBody": "EMSA",
      "jurisdiction": "EU",
      "applicablePeriod": { "startDate": "2025-01-01", "endDate": "2025-12-31" }
    }
  },
  "obligation": {
    "obligationType": "GHG_INTENSITY_COMPLIANCE",
    "targetEntity": { "entityType": "vessel", "entityId": "IMO:9876543" },
    "thresholds": [{ "metric": "GHG_INTENSITY_WTW", "value": 91.16, "unit": "gCO2eq/MJ" }],
    "regulatoryReference": "FuelEU Maritime Regulation, Article 4"
  }
}

Evidence Artefact (GHG Measurement)

{
  "ards:meta": {
    "ardsVersion": "1.0.0",
    "schemaId": "https://schema.axiomordo.com/ards/1.0/evidence-artefact/evidence-artefact.schema.json",
    "schemaVersion": "1.0.0",
    "artefactType": "EvidenceArtefact",
    "artefactId": "urn:uuid:7b2e9f41-3a8d-4c12-b5e7-d9f0a1b2c3d4",
    "producedAt": "2026-01-20T14:30:00Z",
    "producerIdentity": {
      "system": "MeasurementPlatform",
      "systemVersion": "2.0.1",
      "organisation": "ClassNK Verification Services"
    },
    "regulatoryContext": {
      "regulation": "FuelEU Maritime",
      "regulatoryBody": "EMSA",
      "jurisdiction": "EU",
      "applicablePeriod": { "startDate": "2025-01-01", "endDate": "2025-12-31" }
    }
  },
  "evidence": {
    "evidenceType": "MEASUREMENT",
    "sourceType": "THIRD_PARTY_VERIFIED",
    "obligationRef": "urn:uuid:3f8e4a21-7c1b-4d09-9e12-a5b6c7d8e901",
    "verificationStatus": "VERIFIED",
    "verifierOrganisation": "ClassNK",
    "evidenceData": {
      "ghgIntensityWtW": 88.4,
      "unit": "gCO2eq/MJ",
      "measurementPeriod": { "startDate": "2025-01-01", "endDate": "2025-12-31" }
    }
  }
}

Compliance Verdict

{
  "ards:meta": {
    "ardsVersion": "1.0.0",
    "schemaId": "https://schema.axiomordo.com/ards/1.0/compliance-verdict/compliance-verdict.schema.json",
    "schemaVersion": "1.0.0",
    "artefactType": "ComplianceVerdict",
    "artefactId": "urn:uuid:c4d5e6f7-8a9b-4c0d-be12-f3a4b5c6d7e8",
    "producedAt": "2026-02-01T10:00:00Z",
    "producerIdentity": {
      "system": "ComplianceEngine",
      "systemVersion": "1.5.0",
      "organisation": "Nordic Maritime GmbH"
    },
    "regulatoryContext": {
      "regulation": "FuelEU Maritime",
      "regulatoryBody": "EMSA",
      "jurisdiction": "EU",
      "applicablePeriod": { "startDate": "2025-01-01", "endDate": "2025-12-31" }
    }
  },
  "verdict": {
    "outcome": "COMPLIANT",
    "obligationRef": "urn:uuid:3f8e4a21-7c1b-4d09-9e12-a5b6c7d8e901",
    "evidenceRefs": ["urn:uuid:7b2e9f41-3a8d-4c12-b5e7-d9f0a1b2c3d4"],
    "determinedAt": "2026-02-01T10:00:00Z",
    "determinedBy": { "type": "AUTOMATED", "system": "ComplianceEngine" }
  }
}

Integration Patterns

Generate & Embed

If you're building a compliance SaaS, generate ARDS artefacts as your native output format. Embed your certificationId in every ards:meta envelope to signal certified status automatically.

Target cert level: L4 Certified Generator

Ingest & Process

If you're building a data pipeline or regulatory portal, implement an ARDS consumer. Validate incoming artefacts with ards-validate before processing. Reject non-conformant inputs gracefully.

Target cert level: L5 Certified Consumer

Full Platform

If you're building a compliance operating system, implement both generation and consumption. Maintain a live provenance graph using Trace Bundles. Export sealed Audit Packages for regulators.

Target cert level: L6 Certified Platform

Frequently Asked Questions

Do I need permission to implement ARDS?

No. ARDS is published under AOSL-1.0, which grants a free, perpetual, irrevocable licence to implement, use, and distribute ARDS. No registration, notification, or fee is required to implement the standard.

Is certification mandatory?

No. L1–L2 are self-declared and free. L3–L6 certification is optional but strongly recommended if you are selling to enterprise buyers or regulated industries. Certification is the market signal of technical credibility.

Can I add my own fields to ARDS artefacts?

Yes. Use the x-vendor: prefix convention for unofficial extensions, or register a namespace via the RFC process. Unregistered fields with the x- prefix are always allowed.

What happens if the standard changes?

ARDS uses SemVer. Minor and patch releases are backward-compatible. Major version changes require a 24-month deprecation notice. All prior versions remain permanently available at their canonical schema URIs.

How do I propose a new domain pack?

Submit an RFC via the RFC process. Include a description of the regulatory domain, the schema families required, and a draft of at least the obligation-record schema. AxiomOrdo will assign a domain working group chair.

Build on ARDS