Required meta-data for code generation

[gregsdennis]

When generating a schema from a type, we generally have all of the information we need. (I'm having trouble thinking of a type declaration that doesn't have enough information to define a schema.)

However, code generation sometimes requires some annotative keywords. For example,

{
  "type": "object",
  "properties": {
    "foo": { "type": "integer" },
    "bar": { "type": "string" }
  }
}

provides enough information to describe the structure of a type, but a type usually needs a name.

Some types don't need this, though. For an array of objects,

{
  "type": "array",
  "items": { /* ... */ }
}

most languages have one or more built-in collection types that can handle this, e.g. List<T> in .Net or NSArray in Objective-C, or even a simple array (which probably every usable language has).

For custom objects, though, in order to generate type code correctly, there should be a minimum amount of information present. Specifically,

• title should hold the type name
• description could map to a comment or other in-code documentation about the type
• any other ideas?

We also need to identify when these should be required. Can that be represented in a meta-schema, or will that be up to the generator to decide?

[yordis]

My only concern: Human-readable vs. Computer IDs

The title seems to be used for humans and "leverage" for computer stuff, making it extremely suboptimal.

Whatever you do, please give us answers for both cases.

[gregsdennis]

@yordis are you then proposing that this vocabulary define a new annotation keyword to specify a type name?

I'd like to define as little as possible, assigning meaning in this context to keywords we already have, but I'm not opposed to a new keyword if it's needed.

[gregsdennis]

Another aspect we should consider is limitations of type naming in various programming languages. We should probably stick with common ground.

Most languages share support for various casings of alphanumeric-with-underscore (e.g. ^[a-z_]+[a-z_0-9]*$), so maybe that's a good place to start.

[yordis]

@yordis are you then proposing that this vocabulary define a new annotation keyword to specify a type name?

Most definitely, there has been few discussion around it and JSON Schema is lacking of a global key that allows programmers to reserve the value for code-gen sake.

[gregsdennis]

It may be helpful (in general) if you could link to those discussions. Thanks for the input.

[gregsdennis]

After considering a bit, I think I'm inclined to agree that a dedicated type name annotation keyword would be ideal. If title is already being used as a validation annotation, there needs to be something to serve a code generation purpose.

Defining when to make this required will be interesting.

[fariadev22]

Just came across this issue and thought I'd link a discussion I initiated back in March since it seems to be more relevant here: OAI/sig-moonwalk#54.

[to-miz]

I think using title with a implementation defined transformation ie. PascalCase should be sufficient, many code generators already do this. Source code is generally human-readable and I think this is preferable to having redundant annotations like

{
    "title": "Foo Type",
    "genTitle": "FooType"
}