How do you define generic-like schemas?

[GabenGar]

Suppose I would like to create an equivalent of this generic type but in schema:

interface IAPIResponseSuccess<DataType> {
  ok: true
  data: DataType
}

interface IAPIResponseFailure {
  ok: false
  errors: string[]
}

type IAPIResponse<DataType> = IAPIResponseSuccess<DataType> | IAPIResponseFailure

I presume without generics it would look like this:

{
  "$id": "api-response"
  "title": "APIResponse",
  "type": "object",
  "required": ["ok"],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
           "const": true
         }
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        },
        "errors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  ]
}

And the schema at some endpoint like this (skipping all request/response related properties and only focus on body):

{
  "allOf": [
    {
      "$ref": "api-response"
    },
    "data": {
      "$ref": "some-other-schema"
    }
  ]
}

It doesn't exactly match the generic behaviour, but the top level can be processed by a decorator to figure out if it's a failure or a success interface, so not too much boilerplate.
Is this the way to go? Kinda sad this setup doesn't translate back into a generic interface in the code and thus will end up in a million non-generic interface imports.

[handrews]

The general schema approach (mix in the specific component of the generic at point-of-use with allOf and $ref) seems correct. As far as how it translates into code, you'll need to ask that on the repo of the implementation you're using.

[GabenGar]

Well it doesn't depend on implementation, since the way the schema structured is akin to a type union, which is semantically different from a generic type even if their usage might end up being similar.

[gregsdennis]

I've actually been considering doing a blog post on this.

This is a perfect application for 2020-12's $dynamicAnchor and $dynamicRef.

Let's start with the generic definition.

interface IAPIResponseSuccess<DataType> {
  ok: true
  data: DataType
}

For this, we want to create the wrapper without knowing what DataType is.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://my.server/IAPIResponseSuccess",
  "type": "object",
  "$defs": {
    "DataType": {
        "$dynamicAnchor": "DataType",
        "not": true
    }
  },
  "properties": {
    "ok": { "const": true },
    "data": { "$dynamicRef": "#DataType" }
  },
  "required": [ "ok", "data" ]
}

So this schema defines an object with an ok property that must have a value of true and a data property that never validates. That's the not: true bit. We can't just use false here because we need the $dynamicAnchor.) Basically this means that you can never have a JSON instance that validates against only the IAPIResponseSuccess schema.

Now it gets interesting. Let's fill in the data.

For simplicity, suppose we want the data to simply be an string: IAPIResponse<string>. For this, we need a new schema that references the generic one above and provides a new $dynamicAnchor for DataType.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://my.server/IAPIResponseSuccessOfString",
  "$defs": {
    "DataType": {
        "$dynamicAnchor": "DataType",
        "type": "string"
    }
  },
 "$ref": "https://my.server/IAPIResponseSuccess"
}

Then you validate JSON data where you expect data to be a string against this schema.

The way this works (and @handrews or @jdesrosiers can probably explain this better) is that your "dynamic scope" starts with the root schema (IAPIResponseSuccessOfString). It defines a $dynamicAnchor: DataType and then $refs into the generic definition. The generic definition also declares $dynamicAnchor: DataType but at this point, we already have that defined, so it's ignored here. When evaluation hits $dynamicRef: #DataType, it uses the first one from the beginning of the dynamic scope, which is the one at the root.

So now this instance will pass:

{
  "ok": true,
  "data": "some string"
}

---

To get the union with IAPIResponseFailure, use oneOf just like you've done.

[jdesrosiers]

So do I understand it right that dynamic and static anchors create an implicit namespace on the schema?

I'm not sure what you mean by that exactly, but that doesn't sound right. Anchors as just a marker labeling a position in the JSON document.

Is it a requirement for the key of $dynamicAnchor declaration within $defs to be the same as the value for the anchor?

No, $defs has nothing to do with the dynamic anchor declaration. It's just a convenient place to put a schema.

If they are different, does it mean the dynamic anchor in the declaration like this: [...] Can be referenced by two different ways i.e. #$defs/key and #anchorKey?

What's technically allowed is a bit complicated, but the only usage that makes sense is for a dynamic reference to reference a dynamic anchor. Other usages end up in the dynamic reference just behaving like a regular reference so you should just use a regular reference instead. In the next release, it's likely that the part that makes the answer to this question complicated will go away and the only thing you will be able to reference from a dynamic reference is a dynamic anchor.

[GabenGar]

I'm not sure what you mean by that exactly, but that doesn't sound right. Anchors as just a marker labeling a position in the JSON document.

Let's say we have schemas A, B and C. A and B have a dynamic anchor some-dynamic-ref declared on them. C references both schemas and also declares some-dynamic-ref. What is the behaviour of that dynamic ref in C?

[handrews]

So do I understand it right that dynamic and static anchors create an implicit namespace on the schema?

Both $anchor and $dynamicAnchor create URI fragments (like HTML's id attribute). Fragments are relative to a base URI, which is explicitly set by $id (and if not set that way, governed by RFC 3986, which usually means the schema's retrieval URI).

The only difference between $anchor and $dynamicAnchor in draft 2020-12 is that when $dynamicRef targets a $dynamicAnchor-created fragment, there is special dynamic behavior. Otherwise, the $dynamicAnchor fragment is just a normal URI fragment.

Let's say we have schemas A, B and C. A and B have a dynamic anchor some-dynamic-ref declared on them. C references both schemas and also declares some-dynamic-ref. What is the behaviour of that dynamic ref in C?

The $dynamicRef behavior when targeting $dynamicAnchor searches the dynamic scope and checks for a $dynamicAnchor-created URI fragment of the same name as the fragment in the $dynamicRef value for each base URI associated with each scope, and resolves to the one associated with the furthest (first-evaluated) active scope.

Therefore it is impossible to answer your question without evaluating an instance with those schemas. That is the entire point of $dynamicRef: to determine the resolution at runtime, unlike normal $ref (or HTML's <a href="...">, or URI-based links in general).

$dynamicRef's "try this fragment out with multiple base URIs and then choose the farthest one" is not normal URI-referencing behavior, so in the future we might make $dynamicAnchor and $dynamicRef use something other than URIs so the different behavior is more intuitive.

Can be referenced by two different ways i.e. #$defs/key and #anchorKey?

Those are just two different fragment syntaxes. You can reference them normally. The only special case is that if $dynamicRef references a fragment created by $dynamicAnchor, then the additional behavior described a few paragraphs above happens. If anything else (e.g. $ref) references fragments, they just behave like normal fragments no matter how they were created ($anchor, $dynamicAnchor, or the structure of the JSON document as expressed in a JSON Pointer fragment).

[GabenGar]

Therefore it is impossible to answer your question without evaluating an instance with those schemas. That is the entire point of $dynamicRef: to determine the resolution at runtime, unlike normal $ref (or HTML's <a href="...">, or URI-based links in general).

The declaration for C is along the lines of:

{
  "properties": {
    "a": {
      "$ref": "A"
    },
    "b": {
      "$ref": "B"
    }
  }
}

So does declaring some-dynamic-ref change the value in both keys?

[handrews]

I don't even know what you're asking at this point. If you want to know how something evaluates, and how that changes between using $dynamic* vs regular $ref/$anchor, you need to show:

• the complete schema using $ref/$anchor
• the complete schema using $dynamicRef/$dynamicAnchor
• the complete instance or instances being evaluated