interagent / prmd

JSON Schema tools and doc generation for HTTP APIs
MIT License
2.1k stars 172 forks source link

Nullable enum #324

Closed niaeashes closed 1 year ago

niaeashes commented 7 years ago

I want to use (example):

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "oneOf": [
        {
          "type": [
            "null"
          ]
        },
        {
          "type": [
            "string"
          ],
          "enum": [
            "type1",
            "type2"
          ]
        }
      ]
    }
  }
}

Note: simple type: ["null", "string"] with "enum" schema is invalid. https://jsonschemalint.com/#/version/draft-04/markup/json?gist=22cb20d97158bce3b1a632ef165b6db6

But, PRMD Verify is not support "oneOf" in definitions. so this schema is refuse via rake schema:verify, but I want to verify it.

Any ideas? Update PRMD::Verify?

Error message:

dist/schema.json: #/definitions/resource/properties/type: failed schema #/definitions/resource/properties/properties/patternProperties/^[a-z0-9][a-zA-Z0-9_]*[a-zA-Z0-9]$: No subschema in "anyOf" matched.
rake aborted!
niaeashes commented 7 years ago

Test API Schemata.

----
"$schema": http://json-schema.org/draft-04/hyper-schema
title: Resource
description: Example Resource
stability: development
type:
- object
definitions:
  type:
    description: Resource Type Name
    oneOf:
      - type: ["string"]
        enum:
        - type1
        - type2
      - type: ["null"]
properties:
  type:
    "$ref": "/schemata/resource#/definitions/type"
id: schemata/resource

This example has 2 problem.

  1. Missmatch interagent-hyper-schema.json

interagent-hyper-schema.json is required type and example, or type: object. Ref: https://github.com/interagent/prmd/blob/master/schemas/interagent-hyper-schema.json#L88

  1. Failure to generate doc via schema:doc

This problem is: how to convert oneOf schema to humanized attribute's explain.

geemus commented 7 years ago

Sorry for the delay, we could probably loosen the hyper-schema definition as you suggest, though generating good documentation may be challenging. Do you have a sense of what you would like the result to look like?