Documentation
¶
Overview ¶
Package classicschema derives the committed Classic API schema artifact, specs/classic/schemas.json, from jamfplatform-go-sdk's published classic_api_resource_documentation.json.
The Classic API manifest (specs/classic/resources.yaml) says which resources the CLI ships and how their URLs are built. It says nothing about what goes *inside* a request body, so `classic-policies create` could only ever tell a caller to pipe XML at it. The SDK's Classic spec carries that missing half — 161 component schemas, 145 enum constraints, 1382 examples and a `required` list on 62 of them — and this package is how it reaches the generator.
Why an artifact rather than reading the SDK spec directly ¶
The same reason specs/gateway/coverage.json exists: `make generate` and CI have to work in a tree where nobody has an SDK checkout. specs/.platform-source is gitignored, so a generator that read it directly would emit a different CLI depending on what a developer last dropped there.
Why the artifact carries no paths ¶
classic_api_resource_documentation.json describes Jamf Pro APIs this repo already generates from specs/classic/resources.yaml, which is why the Makefile keeps it in PLATFORM_SDK_COVERAGE_SPECS and warns that it must never join PLATFORM_SDK_SPECS — handing it to the platform generator emits a second set of Pro commands built from gateway paths.
Committing a trimmed copy into specs/classic/ puts that same hazard next door to a file the generator does read. So the artifact keeps components.schemas and drops `paths` entirely: with no operations in it, no generator can produce a command from it even if one is pointed at it by mistake. The resource-to-schema mapping the paths used to provide is resolved here, at derivation time, and recorded in x-jamf-classic-resources.
Index ¶
Constants ¶
const ArtifactFile = "classic/schemas.json"
ArtifactFile is the committed artifact's path relative to the specs directory.
const SourceFile = "classic_api_resource_documentation.json"
SourceFile is the SDK spec this package derives from. Same file the gateway coverage manifest reads, and the same drop directory.
Variables ¶
This section is empty.
Functions ¶
func CarryForwardProvenance ¶
func CarryForwardProvenance(a, prev *Artifact)
CarryForwardProvenance keeps a recorded SDK revision that this run was not told, so re-deriving from unchanged specs does not blank it.
Same reasoning as gateway.CarryForwardProvenance: without it, `make verify-classic-schemas` reports a stale artifact that is byte-identical apart from the one field the verification run just erased.
Types ¶
type Artifact ¶
type Artifact struct {
OpenAPI string `json:"openapi"`
Info Info `json:"info"`
Source Source `json:"x-jamf-source"`
Resources map[string]*Res `json:"x-jamf-classic-resources"`
Components Components `json:"components"`
}
Artifact is the committed schema artifact. It is a deliberately partial OpenAPI 3 document: Components is populated and Paths is absent, so nothing can generate a command from it.
func Extract ¶
func Extract(srcDir, sdkCommit string, manifest []ManifestEntry) (*Artifact, []string, error)
Extract derives the artifact from the SDK spec in srcDir, binding each manifest entry to a component schema.
Returns the artifact plus warnings: one per manifest resource whose schema could not be resolved, and one per resource whose manifest `singular` disagrees with the schema's XML root. Neither is fatal. An unresolved resource simply ships without body help, which is the state every Classic resource is in today, and four of the six unresolved ones are resources the gateway has already withdrawn.
type Components ¶
type Components struct {
Schemas map[string]json.RawMessage `json:"schemas"`
}
Components holds the schema map, keyed by component name.
type ManifestEntry ¶
ManifestEntry is the subset of a specs/classic/resources.yaml entry this package needs. Passed in rather than parsed here, so generator/classic stays the only reader of the manifest format.
type Res ¶
type Res struct {
// Schema is the component schema key, e.g. "policy".
Schema string `json:"schema"`
// Root is the XML root element name for a request body. Taken from the
// schema's xml.name when it declares one, else the schema key itself.
Root string `json:"root"`
// From is the spec operation the binding was read off, e.g.
// "GET /policies/id/{id}". Recorded so a surprising binding can be traced
// back to the spec rather than to this package's inference.
From string `json:"from"`
// SingularAgrees is false when the manifest's `singular:` field disagrees
// with Root. The manifest value is what the CLI already sends as the XML
// root and as the JSON unwrap key, so a disagreement is a real conflict
// between two sources of the same fact and is surfaced as a warning rather
// than silently resolved.
SingularAgrees bool `json:"singularAgrees"`
// Singular is the manifest's value, recorded whenever it disagrees.
Singular string `json:"singular,omitempty"`
}
Res binds one CLI Classic resource to the component schema that describes its body, and to the XML root element a request must be wrapped in.
type Source ¶
type Source struct {
Spec string `json:"spec"`
Title string `json:"title"`
Version string `json:"version"`
SDKCommit string `json:"sdkCommit,omitempty"`
Schemas int `json:"schemas"`
Resources int `json:"resources"`
Unresolved int `json:"unresolved"`
}
Source records where the artifact came from, so staleness is checkable without an SDK checkout.
Source Files