The Avro Schema 'name' field should get carried over to the JSON Schema 'title' field.

[damaru-inc]

Describe the bug

When you use an Avro schema in an AsyncAPI document and run it through the parser, the resulting schema has no 'title' attribute set even when the Avro schema had a 'name' attribute.

The schema is presented by the parser as having a name like , but it would be nice for code generators to be able to get the original name somehow.

How to Reproduce

Run the test in this project, you'll see that the 'transforms record values' confirms that no title field appears.

Expected behavior

I would have expected to see the 'name' attribute copied to the 'title' attribute in the generated JSON schema.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

@damaru-inc title will not help much - have a look

the only way to get nice name instead of anonymous name is to get the name into $id, the question is: is Avro name suited for JSON Schema $id

cc @fmvilas

[damaru-inc]

Why do you say that 'title' won't help? I don't think $id is appropriate, because in json schema, the $id field is supposed to be a URI that uniquely identifies the schema, whereas 'title' seems to serve the same purpose as the avro 'name' field. Avro schemas can have ids, but they usually aren't represented in the schema itself, they're often used by kafka to fetch a schema from a schema registry to serialize/deserialize a message. So that would be another thing that would cause confusion, i.e. if we take the avro name and have it come back as an $id property of the resulting json schema.

[derberg]

@damaru-inc Parser works this way now that the name of schema is either $id (as it assures uniqueness) or value under x-parser-schema-id ext as a fallback. x-parser-schema-id in case of schemas from components is the key name that holds schema or anonymous name.

The goal is to get rid of "anonymous" id and be able to use schema directly in the message and not in components, right? This is universal problem no matter if Avro or JSON Schema.

The only solution, for now, is to have $id.

$id field is supposed to be a URI that uniquely identifies the schema

string is also a valid URI. Have a look at this great article from @jonaslagoni and how he uses $id.

[jonaslagoni]

Yea, the problem is JSON Schema has no vocabulary (yet) to help us facilitate the naming of a generated model. So for now we highly misuse $id, as you said because it is designed to be a URI. title could be another option but it is not the right solution either, so for now in the parser we utilize the $id property for this use-case.

We could, as a bandage solution until the general problem is fixed, maybe utilize x-parser-schema-id, what do you think @damaru-inc @derberg ?

[derberg]

maybe utilize x-parser-schema-id

in what way? that avro parser puts Avro name under title and x-parser-schema-id?

[jonaslagoni]

maybe utilize x-parser-schema-id

in what way? that avro parser puts Avro name under title and x-parser-schema-id?

@derberg I don't think @damaru-inc use-case really needs it to be under title (might be wrong!), he just needs to access the uid() of the schema in the template, for generating a model. So the avro parser just needs to put the name under x-parser-schema-id.

[damaru-inc]

I don't mind if the $id or x-parser-schema-id is anonymous. Avro schemas currently have to be under the message, not in components/schemas right? All I want is to be able to access the original Avro 'name' field one way or another, and semantically, that field means the same thing as the Json Schema 'title' field, so it feels like a natural fit.

I guess what I'm saying is I don't mind whether we use the title field or $id or x-parser-schema-id - I don't know the internals of the parser, so I'm not in the best position to say what's the best solution.

[jonaslagoni]

Avro schemas currently have to be under the message, not in components/schemas right?

yes, as your spec issue also points out 🙂

All I want is to be able to access the original Avro 'name' field one way or another, and semantically, that field means the same thing as the JSON Schema 'title' field, so it feels like a natural fit.

Hmmm... I mean if you just want the original Avro properties and don't care about the interpretation, you could always use the original payload?

avro-schema-parser/index.js

Line 7 in fb5a059

message['x-parser-original-payload'] = message.payload;

Of course, the question still remains, how name should be interpreted, and this depends on a few things.

1. Should name be the interpreted unique id of the schema?
   • $id is primarily used across all implementations (at the moment), as the unique id representing the schema between each other. However, it is highly misused based on its description: http://json-schema.org/understanding-json-schema/structuring.html#id. Therefore x-parser-schema-id for now might be the best option.
2. Should name be interpreted as a title for the schema.
   • Remember, title in JSON Schema is basically a short description of the purpose of the data described by the schema.

[derberg]

so far I see that all stars in heaven say that best would be to Avro parser to put name into x-parser-schema-id

[damaru-inc]

I just tried that, writing something like jsonSchema['x-parser-schema-id'] = avroDefinition.name and it seems to work. If you guys think that's the best thing to do, I'll update my PR.

[damaru-inc]

Okay, the PR's updated. This solution will work for me.

[asyncapi-bot]

🎉 This issue has been resolved in version 0.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀