API schema definitions for Apple's various device management web services.
While Apple does provide documentation in the form of HTML (i.e. for humans to read), machine-readable API schema definitions are much preferred for e.g. validation, code generation, etc. We love the documentation Apple provides in the Apple Device Management repository and hope one day they will choose to manage and provide machine-readable schemas for their web service APIs, too. Hopefully these work as a stop-gap until that happens. These schemas were originally hand-crafted from the HTML/JavaScript documentation. The API schemas are now generated from Apple's machine-readable documentation source, the JSON behind the rendered pages (see the retrieval documentation and the generation tool), plus a small set of patches for the details Apple's documentation leaves out.
A general list of schemas managed here:
- ABM Schemas and patches
JSON Schema definitions for the Apple Business Manager API - ASM Schemas and patches
JSON Schema definitions for the Apple School Manager API - DEP + Roster Schemas and patches
JSON Schema definitions for the Device Assignment (DEP) and Roster Management APIs - ANB Schemas
JSON Schema definitions for the App and Book Management (ANB) API - Other schemas
JSON Schema definitions for miscellaneous Apple services such as the Apple Software Lookup Service (GDMF).
Apple's documentation doesn't capture everything: some required fields, enum values, string lengths, formats, and examples are missing. We add those as patches rather than editing the generated schemas, which would be overwritten the next time they're regenerated.
Each schema directory has a patches/ folder beside it, with a JSON Patch (RFC 6902) for each schema that needs one, named after the schema it changes. The patches are applied each time the schemas are regenerated from Apple's documentation.
A patch checks the values it changes before changing them. If Apple's documentation changes underneath a patch, generation fails instead of quietly overwriting the new content, and the patch needs updating. To change a schema, edit its patch, not the generated file.
Each schema directory also has an OpenAPI.json: an OpenAPI 3.1 document describing the service's endpoints — paths, parameters, request bodies, and responses — that references the schemas beside it. The API documents are generated from Apple's documentation along with the schemas, and patched the same way (authentication, for example, isn't in Apple's endpoint data); the GDMF one in other/schemas is written by hand.
These schemas are only as complete as Apple's documentation and our patches, so they're almost guaranteed to be missing something. So: your help needed! If something you need is missing or wrong, PRs are welcome. For a generated schema, add or update its patch rather than editing the schema itself, or improve the generation tool if Apple's documentation already has what's needed.
Note that we use the jsonschema tool to enforce JSON Schema formatting and linting.