Schema Object namespaces

[brendanclement]

I am having the same problem described in #578 -- my use case has the possibility for definition names to clash. For example, you could have multiple User definitions inside a code base. I'm investigating the possibility of implementing (optional) namespaced Schema definitions and looking for feedback on this feature proposal

Some progress was made in #634 to extend legal character set in the 3.0 draft but this was removed in commit 840de94 .

I also found this thread asking for more granularity in specifying the namespace for model definitions: swagger-api/swagger-codegen#3915 - it was suggested that the OP could modify the generator and templates to achieve this

The following definitions will resolve correctly in the swagger ui editor and validator

definitions:
  core.Foobar:
    properties:
      bar:
        $ref : '#/definitions/core.Bar'
  core.Bar:
    properties:
      foo:
        type: string

but the swagger-codegen tooling does not currently honor the namespace. Using JavaCodegen as an example: when the definition above is translated into code class CoreFoobar and class CoreBar are emitted due to the name sanitization in DefaultCodegen.java
The example I gave above defined two normalized shapes, but I'm not sure how to handle namespaces defined in inline definitions (a de-normalized schema). e.g. Which namespace would the child object belong to?

[handrews]

Keeping in mind that I know JSON Schema well but only sort-of know OpenAPI, so this might be obvious to everyone else, but... is there a reason not to just nest definitions sections?

definitions:
  core:
    definitions:
      Foobar:
        properties:
          bar:
            $ref : '#/definitions/core.Bar'
      Bar:
        properties:
          foo:
            type: string

[MikeRalphson]

Neither OASv2 or v3 support the definitions property within SchemaObjects:

Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.

However there is no reason not to use a containing object to hold the nested structure and to reference it deeply:

components:
  schemas:
    core:
      properties:
        foo:
          type: string
        bar:
          type: string
    MyFoo:
      $ref: '#/components/schemas/core/foo'

Unsure how swagger-codegen handles that, but that's an issue for that repo, not really here.

[darrelmiller]

@brendanclement The allowed characters for naming reusable components (including schemas) is defined here https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject and is the same as was proposed in #634

We did briefly have some guidance around the notion of namespaces, but that was simply to suggest that if you want to namespace component names then we recommend using a dot. However, this was simply a recommendation and we did not try to formalize the concept of namespaces. Code-gen tooling is going to have to take it's own approach to determining how to convert names into names and namespaces.

[ayush5148]

Neither OASv2 or v3 support the definitions property within SchemaObjects:

Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.

However there is no reason not to use a containing object to hold the nested structure and to reference it deeply:

components:
  schemas:
    core:
      properties:
        foo:
          type: string
        bar:
          type: string
    MyFoo:
      $ref: '#/components/schemas/core/foo'

Unsure how swagger-codegen handles that, but that's an issue for that repo, not really here.

Were you able to support this use case?

[karenetheridge]

OpenAPI v3.1 uses JSON Schema draft2020-12 for its schema definitions, which fully supports using $defs anywhere a schema is valid, and a $ref to any subschema (even if it's not right at /components/schemas/ should be legal as well (although that's not as explicit in the OpenAPI spec as perhaps it could be).

[ayush5148]

@karenetheridge thanks for the reply. Can you provide me an example for the same?

[karenetheridge]

This should work:

components:
  schemas:
    foo:
      $defs:
        bar:
          type: string
paths:
  /foo/{foo_id}/bar:
    get:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/foo/$defs/bar'