From 23c1718ae2d1a429b77e6b4ded039f674d023080 Mon Sep 17 00:00:00 2001 From: Esteban Zimanyi Date: Thu, 19 Nov 2026 09:09:25 +0100 Subject: [PATCH] Validate every document against the schema resolutions 1 to 5 make The wiki page of Part 1 offers the Standards Working Group five candidate resolutions of the normative schemas. ats_resolved_schema_test.go implements them: it reads the vendored bundle, applies each resolution in memory at the sites it names, each site asserted to hold the published text first, and writes nothing back. The walk over the published examples moves out of TestATSSchemaPublishedExamples into publishedExamples, which both files read. Resolution 3 keeps the three-character branch of a form and gives it the UN/CEFACT common-code pattern, since the standard's own examples write their units as KMH, MTR and MQS. Resolution 5 gives the datetimes of every temporal value the RFC 3339 pattern beside format: date-time, so that a validator reading format as an annotation constrains them too. Measured, under either reading of format: every document the service writes is valid against the resolved schema; 5 of 16 published examples fail it, the five whose example is wrong against a right schema, against 10 or 13 of 16 published; and no document valid against the published schema fails the resolved one. The narrowings each resolution makes (a scalar values, a unit such as deg, an instant that is no RFC 3339 date-time) are cases of the test. --- ats_resolved_schema_test.go | 596 ++++++++++++++++++++++++++++++++++++ ats_schema_test.go | 86 +++--- openapi/README.md | 29 ++ 3 files changed, 673 insertions(+), 38 deletions(-) create mode 100644 ats_resolved_schema_test.go diff --git a/ats_resolved_schema_test.go b/ats_resolved_schema_test.go new file mode 100644 index 0000000..c104ff2 --- /dev/null +++ b/ats_resolved_schema_test.go @@ -0,0 +1,596 @@ +// The resolved schema: the OGC API – Moving Features Part 1 document with candidate +// resolutions 1 to 5 of the wiki page "Implementing OGC API — Moving Features in +// MobilityDB" applied, and every document this tier writes and every example OGC +// publishes validated against it. +// +// A resolution is offered to the Standards Working Group with its implementation as +// evidence, never as text alone. This file is that implementation for the five edits +// of the normative schemas: it shows each one can be written as a schema a validator +// compiles, that it answers the cases it exists for, and what it does to the +// documents that exist today. +// +// It reads the vendored document as ats_schema_test.go does (#ogcSchemasFormat, +// #openAPINullable) and the published examples through #publishedExamples, and adds +// only the resolutions. +// +// ⛔ THE VENDORED COPY IS NEVER EDITED. resolvedOGC reads it and builds the resolved +// document in memory, each resolution an edit at the sites the wiki names, and each +// site asserted to hold the published text before it is edited: a vendored document +// that moved fails here instead of being resolved into something nobody proposed. +package main + +import ( + "bytes" + "encoding/json" + "os" + "path/filepath" + "reflect" + "sort" + "strings" + "testing" + + "github.com/santhosh-tekuri/jsonschema/v6" +) + +// absoluteURIPattern is the pattern resolution 1 gives the URI branch of a `oneOf`, +// so that it stops overlapping the branch of named values. It is the pattern +// #TestATSSchemaMotionCurveIsInverted measures on motionCurve alone. +const absoluteURIPattern = "^[A-Za-z][A-Za-z0-9+.-]*:" + +// unCEFACTCodePattern is the pattern resolution 3 gives the three-character branch of +// a `form`: a UN/CEFACT Recommendation 20 common code, as the standard's own examples +// write their units (`KMH`, `MTR`, `MQS`). It holds no `:`, so it cannot overlap the +// URI branch of resolution 1 whichever way a validator treats `format`. +const unCEFACTCodePattern = "^[A-Z0-9]{3}$" + +// rfc3339Pattern is the pattern resolution 5 gives the instants of a temporal value: +// the date-time of RFC 3339 section 5.6, which the standard names as their syntax. It +// states in a pattern what `format: date-time` states only to a validator that +// asserts `format`, so the instants are constrained under either reading. +const rfc3339Pattern = `^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$` + +// valueInterpolationSchema is the name resolution 4 gives the one schema of a +// property's value interpolation, which the published document spells inline. +const valueInterpolationSchema = "valueInterpolation" + +// resolutionSites is how many places each resolution edits. Asserting the counts is +// what keeps a resolution from silently ceasing to apply, as #nullableRewrites does +// for the nullable rewrite. +var resolutionSites = map[int]int{ + 1: 6, // the URI branch of motionCurve, of the three inline interpolations and of the two forms + 2: 1, // temporalPrimitiveValue.values + 3: 2, // temporalProperty.form and parametricValues.*.form + 4: 4, // the three inline interpolations and temporalPrimitiveValue.interpolation + 5: 3, // the datetimes of temporalPrimitiveGeometry, temporalPrimitiveValue and parametricValues +} + +// at walks a decoded JSON document along a path of object keys and array indexes. +func at(t *testing.T, doc any, path ...any) any { + t.Helper() + cur := doc + for i, step := range path { + switch s := step.(type) { + case string: + m, ok := cur.(map[string]any) + if !ok { + t.Fatalf("resolving %v: %v is not an object", path, path[:i]) + } + if cur, ok = m[s]; !ok { + t.Fatalf("resolving %v: no member %q at %v", path, s, path[:i]) + } + case int: + a, ok := cur.([]any) + if !ok || s >= len(a) { + t.Fatalf("resolving %v: no item %d at %v", path, s, path[:i]) + } + cur = a[s] + } + } + return cur +} + +// object answers the object at path, failing when there is none. +func object(t *testing.T, doc any, path ...any) map[string]any { + t.Helper() + m, ok := at(t, doc, path...).(map[string]any) + if !ok { + t.Fatalf("resolving %v: not an object", path) + } + return m +} + +// decode reads a JSON text the way the validator does. +func decode(t *testing.T, src string) any { + t.Helper() + v, err := jsonschema.UnmarshalJSON(strings.NewReader(src)) + if err != nil { + t.Fatalf("%s is not JSON: %v", src, err) + } + return v +} + +// expect asserts a site holds the published text before a resolution edits it. +func expect(t *testing.T, r int, got any, want string, path ...any) { + t.Helper() + if !reflect.DeepEqual(got, decode(t, want)) { + b, _ := json.Marshal(got) + t.Fatalf("resolution %d: %v holds %s, want the published %s: the vendored document moved, "+ + "so re-read the wiki page before resolving it", r, path, b, want) + } +} + +const ( + publishedURIBranch = `{"type":"string","format":"uri"}` + resolvedURIBranch = `{"type":"string","format":"uri","pattern":"^[A-Za-z][A-Za-z0-9+.-]*:"}` + publishedThreeCharForm = `{"type":"string","minLength":3,"maxLength":3}` + publishedValueEnum = `{"type":"string","enum":["Discrete","Step","Linear","Regression"],"default":"Linear"}` + publishedPrimitiveValue = `{"type":"string","enum":["Discrete","Step","Linear","Regression"]}` +) + +// publishedOGC decodes the vendored document as the validator reads it, with the +// nullable rewrite of #ogcSchemasFormat applied and nothing else. Each call answers a +// fresh tree, so a resolution edits nothing another reader holds. +func publishedOGC(t *testing.T) any { + t.Helper() + f, err := os.Open(ogcBundlePath) + if err != nil { + t.Fatalf("the vendored OGC schemas are missing: %v", err) + } + defer f.Close() + raw, err := jsonschema.UnmarshalJSON(f) + if err != nil { + t.Fatalf("reading %s: %v", ogcBundlePath, err) + } + var rewritten int + doc := openAPINullable(raw, &rewritten) + if rewritten != nullableRewrites { + t.Fatalf("the nullable rewrite fired %d times, want %d", rewritten, nullableRewrites) + } + return doc +} + +// resolvedOGC reads the vendored document and answers it with resolutions 1 to 5 +// applied, and how many sites each resolution edited. +func resolvedOGC(t *testing.T) (any, map[int]int) { + t.Helper() + doc := publishedOGC(t) + schemas := object(t, doc, "components", "schemas") + edits := map[int]int{} + + pv := func(i int) []any { + return []any{"components", "schemas", "parametricValues", "additionalProperties", "oneOf", i, "properties"} + } + // Resolution 1: the URI branch of each of the six `oneOf` takes an absolute-URI + // pattern, so that a named value matches the enum alone, an absolute URI the URI + // branch alone, and an arbitrary string neither. + for _, site := range [][]any{ + {"components", "schemas", "motionCurve", "oneOf", 1}, + append(pv(0), "interpolation", "oneOf", 1), + append(pv(1), "interpolation", "oneOf", 1), + append(pv(2), "interpolation", "oneOf", 1), + append(pv(0), "form", "oneOf", 1), + {"components", "schemas", "temporalProperty", "properties", "form", "oneOf", 0}, + } { + branch := object(t, doc, site...) + expect(t, 1, branch, publishedURIBranch, site...) + branch["pattern"] = absoluteURIPattern + edits[1]++ + } + + // Resolution 2: a value per instant, `values` an array mirroring `datetimes` with + // the published scalar `oneOf` as its items. + tpv := object(t, doc, "components", "schemas", "temporalPrimitiveValue", "properties") + expect(t, 2, tpv["values"], + `{"oneOf":[{"type":"number"},{"type":"string"},{"type":"boolean"}]}`, + "temporalPrimitiveValue", "values") + tpv["values"] = map[string]any{ + "type": "array", + "minItems": decode(t, "2"), + "items": tpv["values"], + } + edits[2]++ + + // Resolution 3: a unit is a register URI or a UN/CEFACT common code. The branch of + // three characters stays, since the standard's own examples write their units in + // it, and takes the pattern of a common code, so that it stops overlapping the URI + // branch and stops admitting any three characters. + for _, site := range [][]any{ + append(pv(0), "form", "oneOf", 0), + {"components", "schemas", "temporalProperty", "properties", "form", "oneOf", 1}, + } { + branch := object(t, doc, site...) + expect(t, 3, branch, publishedThreeCharForm, site...) + branch["pattern"] = unCEFACTCodePattern + edits[3]++ + } + + // Resolution 4: a property's value interpolation is spelled once, as a named + // schema, and every site that spells it refers to it. The three inline copies are + // identical once resolution 1 has applied, which is asserted, so hoisting them + // changes no answer; temporalPrimitiveValue.interpolation, the fourth site, takes + // the same schema and so gains the URI branch the inline copies carry. + inline := `{"oneOf":[` + publishedValueEnum + `,` + resolvedURIBranch + `]}` + ref := map[string]any{"$ref": "#/components/schemas/" + valueInterpolationSchema} + for i := 0; i < 3; i++ { + props := object(t, doc, pv(i)...) + expect(t, 4, props["interpolation"], inline, "parametricValues", i, "interpolation") + props["interpolation"] = ref + edits[4]++ + } + expect(t, 4, tpv["interpolation"], publishedPrimitiveValue, "temporalPrimitiveValue", "interpolation") + tpv["interpolation"] = ref + edits[4]++ + if _, taken := schemas[valueInterpolationSchema]; taken { + t.Fatalf("resolution 4: the published document already names a schema %q", valueInterpolationSchema) + } + schemas[valueInterpolationSchema] = decode(t, inline) + + // Resolution 5: the instants of every temporal value are RFC 3339 date-times, stated + // as `format: date-time` and as the pattern of section 5.6, so that a validator + // that reads `format` as an annotation constrains them too. A temporal geometry's + // instants, published as any string, take both; those of a primitive value and of + // parametric values, published with the format alone, take the pattern. The other + // date-times of the document (a `timeStamp`, the temporal extent, the `leaf` + // parameter) are no instants of a temporal value and are not edited. + for _, c := range []struct { + schema, published string + }{ + {"temporalPrimitiveGeometry", `{"type":"string"}`}, + {"temporalPrimitiveValue", `{"type":"string","format":"date-time"}`}, + {"parametricValues", `{"type":"string","format":"date-time"}`}, + } { + items := object(t, doc, "components", "schemas", c.schema, "properties", "datetimes", "items") + expect(t, 5, items, c.published, c.schema, "datetimes", "items") + items["format"] = "date-time" + items["pattern"] = rfc3339Pattern + edits[5]++ + } + + return doc, edits +} + +// compileOGC compiles a decoded document under a reading of `format` and answers a +// validator per JSON pointer into it; #ogcSchemasFormat does the same for the +// vendored document by schema name. +func compileOGC(t *testing.T, doc any, assertFormat bool) func(string) *jsonschema.Schema { + t.Helper() + c := jsonschema.NewCompiler() + if assertFormat { + c.AssertFormat() + } + if err := c.AddResource("ogc.json", doc); err != nil { + t.Fatalf("loading the document: %v", err) + } + return func(pointer string) *jsonschema.Schema { + s, err := c.Compile("ogc.json#" + pointer) + if err != nil { + t.Fatalf("no schema at %s: %v", pointer, err) + } + return s + } +} + +func schemaPointer(name string) string { return "/components/schemas/" + name } + +// readings are the two readings of `format` JSON Schema allows, as +// #TestATSSchemaPublishedExamples measures them. +var readings = []struct { + what string + assert bool +}{ + {"`format` asserted", true}, + {"`format` as an annotation", false}, +} + +// Every resolution edits exactly the sites the wiki names, and the resolved document +// compiles under either reading. +func TestATSResolvedSchemaEdits(t *testing.T) { + doc, edits := resolvedOGC(t) + if !reflect.DeepEqual(edits, resolutionSites) { + t.Errorf("the resolutions edited %v sites, want %v", edits, resolutionSites) + } + for _, r := range readings { + schema := compileOGC(t, doc, r.assert) + for _, name := range []string{"motionCurve", valueInterpolationSchema, "temporalPrimitiveValue", + "temporalPrimitiveGeometry", "temporalProperty", "parametricValues", "temporalGeometrySequence"} { + schema(schemaPointer(name)) + } + } +} + +// A case of a resolution: a document at a schema site, and whether the published and +// the resolved schemas admit it. A case where the two differ is what the resolution +// changes; a case where they agree pins that it changes nothing else. +type resolutionCase struct { + resolution int + pointer string + doc string + published bool // under `format` asserted + resolved bool // under either reading + // publishedDefault is the published verdict under the annotation reading, where it + // differs from the asserted one. + publishedDefault *bool +} + +func verdict(b bool) *bool { return &b } + +// The cases each resolution exists for, and the documents it narrows. +// +// ⛔ THREE RESOLUTIONS NARROW WHAT THE PUBLISHED SCHEMA ADMITS. A scalar `values` +// (resolution 2), a three-character unit that is no UN/CEFACT common code such as +// `deg` (resolution 3) and a temporal geometry's instant that is no RFC 3339 +// date-time (resolution 5) are admitted today and refused once resolved. Each is a +// document the standard's own text does not admit (a value per instant; RFC 3339) or +// one the resolution means to refuse (a unit neither from a register nor a common +// code), so the narrowing is the resolution; it is stated here as cases rather than +// claimed away. "Every document conformant today stays conformant" +// holds over the documents that exist, the tier's and the standard's examples +// (TestATSResolvedSchemaKeepsEveryDocument), not over every document a schema admits. +func TestATSResolvedSchemaCases(t *testing.T) { + const tp = "/components/schemas/temporalProperty/properties/form" + const pvForm = "/components/schemas/parametricValues/additionalProperties/oneOf/0/properties/form" + const pvInterp = "/components/schemas/parametricValues/additionalProperties/oneOf/0/properties/interpolation" + const tpv = "/components/schemas/temporalPrimitiveValue" + const tpg = "/components/schemas/temporalPrimitiveGeometry/properties/datetimes" + const tpvTimes = "/components/schemas/temporalPrimitiveValue/properties/datetimes" + const pvTimes = "/components/schemas/parametricValues/properties/datetimes" + mc := schemaPointer("motionCurve") + value := func(values, interp string) string { + return `{"datetimes":["2026-01-01T08:00:00Z","2026-01-01T08:10:00Z"],"values":` + values + + `,"interpolation":"` + interp + `"}` + } + + var cases []resolutionCase + // Resolution 1, at a motion curve and at a value interpolation: the named values + // and an absolute URI are admitted and an arbitrary string is not, under either + // reading. Published, the annotation reading inverts both. + for _, p := range []string{mc, pvInterp} { + named := []string{"Discrete", "Step", "Linear"} + if p == mc { + named = append(named, "Quadratic", "Cubic") + } else { + named = append(named, "Regression") + } + for _, v := range named { + cases = append(cases, resolutionCase{1, p, `"` + v + `"`, true, true, verdict(false)}) + } + cases = append(cases, + resolutionCase{1, p, `"http://example.org/curve"`, true, true, nil}, + resolutionCase{1, p, `"Bogus"`, false, false, verdict(true)}) + } + // Resolution 2: a value per instant is admitted, and a scalar beside two instants + // is not. + cases = append(cases, + resolutionCase{2, tpv, value(`[0.0, 20.0]`, "Linear"), false, true, nil}, + resolutionCase{2, tpv, value(`[true, false]`, "Step"), false, true, nil}, + resolutionCase{2, tpv, value(`20.0`, "Linear"), true, false, nil}) + // Resolution 3: a register URI and a UN/CEFACT common code are admitted under + // either reading, the codes the standard's own examples write among them; `deg`, + // three characters and no common code, is refused, as are the symbols the published + // schema never admitted. Published, the annotation reading inverts the branches as + // it does motionCurve's: a common code matches both and is refused, and any string + // longer than three characters matches the URI branch alone and is admitted. + for _, p := range []string{tp, pvForm} { + cases = append(cases, + resolutionCase{3, p, `"http://www.opengis.net/def/uom/UCUM/0/m"`, true, true, nil}, + resolutionCase{3, p, `"http://www.opengis.net/def/uom/UCUM/0/km_h-1"`, true, true, nil}, + resolutionCase{3, p, `"MTR"`, true, true, verdict(false)}, + resolutionCase{3, p, `"KMH"`, true, true, verdict(false)}, + resolutionCase{3, p, `"MQS"`, true, true, verdict(false)}, + resolutionCase{3, p, `"deg"`, true, false, verdict(false)}, + resolutionCase{3, p, `"m"`, false, false, verdict(true)}, + resolutionCase{3, p, `"km/h"`, false, false, verdict(true)}) + } + // Resolution 4: temporalPrimitiveValue.interpolation reads the named schema, so it + // admits a URI as the inline copies do, and its vocabulary is the published one. + cases = append(cases, + resolutionCase{4, tpv, value(`[0.0, 20.0]`, "http://example.org/curve"), false, true, nil}, + resolutionCase{4, tpv, value(`[0.0, 20.0]`, "Regression"), false, true, nil}, + resolutionCase{4, tpv, value(`[0.0, 20.0]`, "Cubic"), false, false, nil}) + // Resolution 5: the instants of a temporal geometry and of a temporal value are + // RFC 3339 under either reading; PostgreSQL's text rendering of a timestamptz is + // not. Published, a geometry's instants are any string, and a value's are + // constrained only when `format` is asserted. + const rfc = `["2026-01-01T08:00:00Z","2026-01-01T08:10:00.5+01:00"]` + const pgText = `["2026-01-01 08:00:00+00","2026-01-01 08:10:00+00"]` + const words = `["yesterday","today"]` + cases = append(cases, + resolutionCase{5, tpg, rfc, true, true, nil}, + resolutionCase{5, tpg, pgText, true, false, nil}, + resolutionCase{5, tpg, words, true, false, nil}) + for _, p := range []string{tpvTimes, pvTimes} { + cases = append(cases, + resolutionCase{5, p, rfc, true, true, nil}, + resolutionCase{5, p, pgText, false, false, verdict(true)}, + resolutionCase{5, p, words, false, false, verdict(true)}) + } + + resolved, _ := resolvedOGC(t) + pub := publishedOGC(t) + narrowed := map[int]int{} + for _, r := range readings { + pubSchema, resSchema := compileOGC(t, pub, r.assert), compileOGC(t, resolved, r.assert) + for _, c := range cases { + v := decode(t, c.doc) + wantPub := c.published + if !r.assert && c.publishedDefault != nil { + wantPub = *c.publishedDefault + } + if got := pubSchema(c.pointer).Validate(v) == nil; got != wantPub { + t.Errorf("resolution %d, %s, published schema with %s: admits %s = %v, want %v", + c.resolution, c.pointer, r.what, c.doc, got, wantPub) + } + if got := resSchema(c.pointer).Validate(v) == nil; got != c.resolved { + t.Errorf("resolution %d, %s, resolved schema with %s: admits %s = %v, want %v", + c.resolution, c.pointer, r.what, c.doc, got, c.resolved) + } + if r.assert && c.published && !c.resolved { + narrowed[c.resolution]++ + } + } + } + t.Logf("cases the published schema admits and the resolved one refuses, by resolution: %v", narrowed) +} + +// sampleSchemas pairs each document the tier writes, as committed under samples/, +// with the schema the bundle attaches to that response. The API definition is an +// OpenAPI document, which no schema of the standard describes. +var sampleSchemas = map[string]string{ + "landing-page.json": "landingPage", + "conformance-declaration.json": "confClasses", + "collections.json": "collections", + "collection.json": "collection", + "moving-feature-collection.json": "movingFeatures", + "moving-feature.json": "movingFeature", + "temporal-geometry-sequence.json": "temporalGeometrySequence", + "temporal-geometry-distance.json": "temporalProperty", + "temporal-geometry-velocity.json": "temporalProperty", + "temporal-geometry-acceleration.json": "exception", + "temporal-properties.json": "temporalProperties", + "temporal-property.json": "temporalProperty", +} + +// corpusDoc is a document that exists today: one the tier writes, or one OGC publishes. +type corpusDoc struct { + what, schema string + doc any +} + +// corpus answers every document the tier writes and every example the bundle pairs +// with a named schema (#publishedExamples). +func corpus(t *testing.T) (samples, examples []corpusDoc) { + t.Helper() + files, err := filepath.Glob("samples/*.json") + if err != nil { + t.Fatal(err) + } + seen := map[string]bool{} + for _, f := range files { + b := filepath.Base(f) + if b == "api-definition.json" { + continue + } + name, ok := sampleSchemas[b] + if !ok { + t.Errorf("samples/%s pairs with no schema of the standard: add it to sampleSchemas", b) + continue + } + seen[b] = true + raw, err := os.ReadFile(f) + if err != nil { + t.Fatal(err) + } + samples = append(samples, corpusDoc{"samples/" + b, name, decode(t, string(raw))}) + } + for b := range sampleSchemas { + if !seen[b] { + t.Errorf("samples/%s is paired with a schema and missing", b) + } + } + pairs, _ := publishedExamples(t) + for _, p := range pairs { + b, err := json.Marshal(p.example) + if err != nil { + t.Fatal(err) + } + examples = append(examples, corpusDoc{"the example at " + p.where, p.name, decode(t, string(b))}) + } + sort.Slice(examples, func(i, j int) bool { return examples[i].what < examples[j].what }) + return samples, examples +} + +// resolvedExampleFailures is how many of the standard's own examples fail the schema +// they are attached to once resolved, under either reading of `format`: the five the +// wiki finds wrong against a right schema (a flat `extent.spatial.bbox` in Collection +// and Collections; a `trs` whose `properties` is a string in MovingFeature, +// MovingFeatures and TemporalGeometrySequence). Published, the count is +// #publishedExampleFailures or #publishedExampleFailuresDefault according to the +// reading; resolved, it is the same under both, which is resolutions 1 and 2 acting +// on the standard's own material. +const resolvedExampleFailures = 5 + +// Every document the tier writes satisfies the resolved schema under either reading, +// and the standard's own examples fail it only where the example is wrong. +func TestATSResolvedSchemaDocuments(t *testing.T) { + samples, examples := corpus(t) + resolved, _ := resolvedOGC(t) + for _, r := range readings { + schema := compileOGC(t, resolved, r.assert) + for _, d := range samples { + if err := schema(schemaPointer(d.schema)).Validate(d.doc); err != nil { + t.Errorf("%s does not satisfy the resolved %s schema with %s:\n%v", + d.what, d.schema, r.what, firstLines(err.Error(), 6)) + } + } + var failed []string + for _, d := range examples { + if err := schema(schemaPointer(d.schema)).Validate(d.doc); err != nil { + failed = append(failed, d.schema) + t.Logf("with %s, %s fails the resolved %s schema:\n %v", + r.what, d.what, d.schema, firstLines(err.Error(), 3)) + } + } + sort.Strings(failed) + t.Logf("with %s: %d of %d published examples fail the resolved schema", r.what, len(failed), len(examples)) + if len(failed) != resolvedExampleFailures { + t.Errorf("with %s, %d of %d published examples fail the resolved schema, want %d: %v", + r.what, len(failed), len(examples), resolvedExampleFailures, failed) + } + for _, f := range failed { + switch f { + case "collection", "collections", "movingFeature", "movingFeatures", "temporalGeometrySequence": + default: + t.Errorf("with %s, a published %s example fails the resolved schema, though the wiki "+ + "finds the examples of that schema right", r.what, f) + } + } + } +} + +// Every document that exists today and satisfies the published schema satisfies the +// resolved one: no resolution takes conformance from a document the tier writes or +// the standard publishes. Measured under each reading of `format`; a document the +// resolutions make conformant is logged, never one they make non-conformant. +func TestATSResolvedSchemaKeepsEveryDocument(t *testing.T) { + samples, examples := corpus(t) + resolved, _ := resolvedOGC(t) + pub := publishedOGC(t) + for _, r := range readings { + pubSchema, resSchema := compileOGC(t, pub, r.assert), compileOGC(t, resolved, r.assert) + var gained, kept int + for _, d := range append(append([]corpusDoc{}, samples...), examples...) { + p := schemaPointer(d.schema) + before, after := pubSchema(p).Validate(d.doc) == nil, resSchema(p).Validate(d.doc) == nil + switch { + case before && !after: + t.Errorf("with %s, %s satisfies the published %s schema and not the resolved one", + r.what, d.what, d.schema) + case before: + kept++ + case after: + gained++ + t.Logf("with %s, %s satisfies the resolved %s schema and not the published one", + r.what, d.what, d.schema) + } + } + t.Logf("with %s: %d documents conformant before and after, %d conformant only once resolved", + r.what, kept, gained) + } +} + +// Resolving reads the vendored document and writes nothing: the bytes on disk are +// still what OGC publishes, as #TestATSSchemaBundleMatchesOGC compares them. +func TestATSResolvedSchemaLeavesTheVendoredCopy(t *testing.T) { + before, err := os.ReadFile(ogcBundlePath) + if err != nil { + t.Fatal(err) + } + resolvedOGC(t) + after, err := os.ReadFile(ogcBundlePath) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(before, after) { + t.Fatalf("resolving %s changed it on disk", ogcBundlePath) + } +} diff --git a/ats_schema_test.go b/ats_schema_test.go index 26df139..b66c1f6 100644 --- a/ats_schema_test.go +++ b/ats_schema_test.go @@ -569,44 +569,7 @@ const ( // defect in the standard, not in this tier, and the count is what makes that // claim checkable instead of quotable. func TestATSSchemaPublishedExamples(t *testing.T) { - raw, err := os.ReadFile(ogcBundlePath) - if err != nil { - t.Fatal(err) - } - var doc any - if err := json.Unmarshal(raw, &doc); err != nil { - t.Fatal(err) - } - type pair struct { - where, name string - example any - } - var pairs []pair - var inline int - var walk func(o any, p string) - walk = func(o any, p string) { - switch v := o.(type) { - case map[string]any: - if s, ok := v["schema"].(map[string]any); ok { - if ex, has := v["example"]; has { - if ref, ok := s["$ref"].(string); ok { - n := ref[strings.LastIndex(ref, "/")+1:] - pairs = append(pairs, pair{p, n, ex}) - } else { - inline++ - } - } - } - for k, sub := range v { - walk(sub, p+"/"+k) - } - case []any: - for i, sub := range v { - walk(sub, fmt.Sprintf("%s[%d]", p, i)) - } - } - } - walk(doc, "") + pairs, inline := publishedExamples(t) if len(pairs) == 0 { t.Fatal("the vendored document pairs no example with a named schema, so this test would assert nothing") } @@ -657,6 +620,53 @@ func TestATSSchemaPublishedExamples(t *testing.T) { "%d responses declare a schema and publish no example at all", inline, exampleless(t)) } +// examplePair is an example the vendored document publishes beside the named schema +// it illustrates. +type examplePair struct { + where, name string + example any +} + +// publishedExamples answers every example the vendored document pairs with a named +// schema, and how many it attaches to an inline schema instead. The pairing is the +// document's own: every example sits in a media-type object beside its schema. +func publishedExamples(t *testing.T) (pairs []examplePair, inline int) { + t.Helper() + raw, err := os.ReadFile(ogcBundlePath) + if err != nil { + t.Fatal(err) + } + var doc any + if err := json.Unmarshal(raw, &doc); err != nil { + t.Fatal(err) + } + var walk func(o any, p string) + walk = func(o any, p string) { + switch v := o.(type) { + case map[string]any: + if s, ok := v["schema"].(map[string]any); ok { + if ex, has := v["example"]; has { + if ref, ok := s["$ref"].(string); ok { + n := ref[strings.LastIndex(ref, "/")+1:] + pairs = append(pairs, examplePair{p, n, ex}) + } else { + inline++ + } + } + } + for k, sub := range v { + walk(sub, p+"/"+k) + } + case []any: + for i, sub := range v { + walk(sub, fmt.Sprintf("%s[%d]", p, i)) + } + } + } + walk(doc, "") + return pairs, inline +} + // exampleless counts the responses that declare a schema and publish no example. // ⛔ THEY ARE NOT PASSES. A row with nothing to validate cannot be one, and counting // it among the examples that satisfy their schema is what makes a tally read better diff --git a/openapi/README.md b/openapi/README.md index 65ecad4..e10a106 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -83,3 +83,32 @@ The failures concentrate in two cells the schemas type in a way no document can `temporalPrimitiveValue.values` is a single scalar beside a `datetimes` array of `minItems: 2`, and `temporalProperty` carries that value object. They are defects in the standard, not in the examples — the examples are what a reader would write. + +## The resolved schema + +The wiki page [Implementing OGC API — Moving Features in +MobilityDB](https://github.com/MobilityDB/MobilityDB/wiki/Implementing-OGC-API-Moving-Features-in-MobilityDB) +offers the Standards Working Group candidate resolutions of the standard. Resolutions 1 to 5 edit +the normative schemas, and `ats_resolved_schema_test.go` implements them: it reads this copy, +applies each resolution in memory at the sites it names (each site asserted to hold the published +text first) and writes nothing back. + +| Resolution | Edit | Sites | +|---|---|---| +| 1 | the URI branch of each `oneOf` takes the absolute-URI pattern `^[A-Za-z][A-Za-z0-9+.-]*:` | 6 | +| 2 | `temporalPrimitiveValue.values` is an array mirroring `datetimes` | 1 | +| 3 | the three-character branch of a `form` takes the UN/CEFACT common-code pattern `^[A-Z0-9]{3}$` | 2 | +| 4 | a property's value interpolation is the named schema `valueInterpolation`, referred to everywhere | 4 | +| 5 | the `datetimes` of a temporal geometry, a temporal primitive value and parametric values take `format: date-time` and the RFC 3339 pattern | 3 | + +Measured against the resolved schema, under either reading of `format`: + +- every document the service writes (`samples/`) is valid; +- **5 of 16** published examples fail, the five whose example is wrong against a right schema + (a flat `extent.spatial.bbox`; a `trs` whose `properties` is a string), against 10 or 13 of 16 + published; +- no document that satisfies the published schema fails the resolved one. + +The resolutions do narrow what the schema admits, and the test states each narrowing as a case: a +scalar `values` (2), a three-character unit that is no common code such as `deg` (3), and an +instant that is no RFC 3339 date-time (5).