Mineral Data Interoperability API

Outcomes

Context

Cross-system mining transparency depends on shared meaning, not only shared CSV columns.

Challenge

Mining oversight systems needed a shared semantic model for sites, licenses, inspections, export certificates, and custody lots — compatible with regional reporting rules and machine-readable exchange.

Approach

We implemented the interoperability technical model as versioned JSON Schemas, OpenAPI specifications, GraphQL/JSON-LD documentation assets, conformance examples, and an API server surface for validation and exchange patterns. Naming, code lists, and ID formats followed the published semantic model.

Architecture

JSON Schema libraries by domain, OpenAPI API contract, GraphQL/JSON-LD documentation, Node API server, conformance fixtures and generation scripts.

Scope

• —Mine site schemas
• —Export certificates
• —Chain-of-custody lots
• —Code lists
• —API/docs generation
• —Conformance examples

Constraints

• —Strict semantic model alignment
• —Regional reporting compatibility
• —Integrators with uneven maturity

Solution highlights

• —Reusable common definitions for address, geo, contacts
• —CamelCase contracts with explicit enums
• —Docs that regenerate from the model, not tribal knowledge

Technologies

Results

• —Complete schema coverage for primary and secondary mining entities
• —Language-independent integer code lists for statuses and roles
• —ICGLR-oriented identifier validation where required
• —Conformance-oriented docs and examples for integrators

Lessons learned

• —Interoperability is a product with versioning and tests.
• —Code lists must be language-independent from day one.
• —Documentation generation prevents silent schema drift.