Reference API & ontology

Data objects, JSON schemas, OpenAPI and AsyncAPI specs, and read-only JSON endpoints for Ethotechnics standards, clauses, and mechanisms.

The object model behind the exports

The names the endpoints and schemas below use. Use the same names in integrations and audit tooling. Each v2 schema has a validating example under /standards/examples/; together the examples describe one delegation scenario.

  • Standard: Top-level standard metadata, version, and published clauses.
  • Clause: One requirement of a standard, with a stable clause ID (for example, §3.2).
  • Mechanism: Reusable enforcement spec with tags, artifacts, and implementation notes.
  • Validator: Diagnostic definition with inputs, thresholds, and output schema.
  • Finding: Canonical diagnostic artifact linking gaps to clauses and fixes.
  • Diagnostic result: Generated report card, risk statement, and remediation recommendations.
  • Evidence pack: The evidence a clause asks a system to be able to show.
  • Crosswalk control: Control-level mapping across the EU AI Act, NIST AI RMF, and ISO/IEC 42001.
  • Post-market stage: Operational incident reporting stages with expected outcomes and references.
  • Anti-pattern: Negative examples that look compliant but fail the clause intent.
  • Diagram: A small figure that explains one term or clause. Diagrams are not exported yet.
  • Agent safety object model: Machine-readable profile for autonomy level, action classes, and receipts; v2.0.0 points each action class at its authority grant. agent-safety-object-model.schema.json
  • Capability catalog: What a grantee can discover it could do. Confers no authority and contains no permission fields. capability-catalog.schema.json
  • Authority grant: A lease on consequential action: scope, evidence basis, state (allowed, review_required, suspended, revoked), and state history. authority-grant.schema.json
  • Policy record: Versioned evidence behind a grant, with assumptions, review triggers, expiry, and status. policy-record.schema.json
  • Dependency record: How hard withdrawal or substitution has become: dependents, reversibility at three levels, preserved capacities, and exposure score. dependency-record.schema.json
  • Standing register and challenge: Who may challenge which decision classes, with what evidence and procedural force; a challenge is one exercise of that standing. standing-register.schema.json challenge.schema.json
  • Intervention spec and reconsideration: What a human can see, prevent, and alter (replacing 'human in the loop'), and the record of an observation changing state. intervention-spec.schema.json reconsideration.schema.json
  • Substrate profile: Nine-property classification of a deployment that replaces open-versus-closed. substrate-profile.schema.json

Interoperability specs

Draft contracts for decision and repair workflows

Specs that wire decisions, appeals, and clock events into tooling.

  • Control plane OpenAPI: /standards/ethotechnics-control-plane.openapi.yaml — Endpoints your system would implement: decision retrieval, appeal intake, and (v0.3.0) capability, grant, policy, dependency, standing, challenge, and reconsideration. None of them runs on ethotechnics.org.
  • Events AsyncAPI: /standards/ethotechnics-events.asyncapi.yaml — Deadline and repair log events, plus (v0.3.0) grant, policy, dependency, challenge, and reconsideration state events.

FHIR resources

FHIR resources (healthcare-specific interop)

  • Target: healthcare payers, providers, and regulators.
  • Why: CMS-0057-F requires Medicare Advantage, Medicaid, and CHIP payers to support FHIR APIs for prior authorization by January 2027, so denials and appeals already travel as FHIR.
  • Status: the profile set here, STD-04, is deprecated. STD-05 carries the same records as W3C Verifiable Credentials.
  • What to ship: custom FHIR profiles for:
    • Decision
    • Denial
    • Appeal
    • RepairStatus
    • PendingClock
  • FHIR makes refusal and repair first-class healthcare data.
  • Decision retrieval: GET /api/decisions/{decision_id}
  • Appeal submission: POST /api/appeals
  • Grant lease and transitions: GET /api/grants/{grant_id}, POST /api/grants/{grant_id}/state
  • Standing and reconsideration: GET /api/standing, POST /api/challenges, POST /api/reconsiderations
  • Events: decision.deadline.reminder, appeal.deadline.breached, repair.log.updated, grant.state.changed, policy.review.triggered, dependency.threshold.crossed, challenge.opened, reconsideration.completed

Files and endpoints

Stable exports for tooling, audits, and archival use.

Endpoint Purpose
/api/agent-index.json Index for agent discovery and tooling.
/api/site-index.json Index of standards, validators, and research metadata.
/api/standards.json Standard metadata with embedded clause objects.
/api/clauses.json Clause-level obligations with evidence requirements and mappings.
/api/mechanisms.json Mechanism catalog entries with filters and citations.
/api/validators.json Validator definitions with inputs, thresholds, and clause mappings.
/api/glossary.json Glossary terms with permalinks.
/api/anti-patterns.json Negative patterns that surface legitimacy theater risks.
/api/evidence-packs.json Evidence pack templates per clause.
/api/crosswalks.json Control crosswalks with framework mappings and evidence artifacts.
/api/post-market-monitoring.json Post-market monitoring and incident reporting workflow stages.
/api/findings.json Canonical finding objects for remediation workflows.
/api/diagnostic-results.json Portable diagnostic result artifacts.
/api/eval-test-cases.json Eval test cases with scoring rubrics and suite assignments.
/api/evals.json Eval suites with scoring methods and passing thresholds.
/api/rag-corpus.jsonl JSONL corpus for retrieval pipelines. Every document carries a layer field: theory, method, or instrument. Add a limit query param for previews.
/api/research.json Research publications and bridge artifacts.
/api/capabilities.json Example capability catalog: what the worked-example agent can reach, with no permission fields.
/api/grants.json Example authority grant with scope, evidence basis, and state history including a narrowing.
/api/policies.json Example policy record with review triggers and expiry.
/api/dependencies.json Example dependency record with three-level reversibility and exposure score.
/api/standing.json Example standing register with its challenge and the reconsideration it triggered.
/api/interventions.json Example intervention spec: what the steward can see, prevent, and alter.
/api/substrate-profiles.json Example substrate profile with the 2.0.0 agent safety object model attached.
/api/releases.json Versioned release index for stable citations.
/api/changelog.json Merged changelog entries for mechanisms and research.
/api/badges.json Repository badges for CI status and license.

Versions, and what is not built

Each object should carry a version, an updated timestamp, and a canonical permalink.

  • Semantic versioning for standards, mechanisms, and validators.
  • Immutable permalinks for citations in contracts and audit logs.
  • Changelogs that describe material changes to rights or thresholds.
  • A release index at /api/releases.json.

Not built, and not scheduled: signed releases with verifiable citation hashes, automated schema validation for new objects, and clause mappings for emerging external standards. The OpenAPI and AsyncAPI drafts above are published.