TypeSpec integration with JSON Schema

[mikekistler]

Services that conform to industry standard data formats, e.g Health Insights and the FHIR standard, would benefit from TypeSpec support to directly import JSON Schema definitions.

An example of where this support would be really useful is the Health Insights service, which works with data that conforms to the FIHR industry standards, which have published JSON schemas, e.g.

observation.schema.json.html

[allenjzhang]

From the issue, there could be different requirements:

• @useRef for emitter to generate correct output which we currently support

• true import of JSON schema into TypeSpec models for in-depth application

1 We do support it already. @mikekistler to check with Health Insight team.

2 Keeping this open on backlog for future design discussions.

[asaflevi-ms]

@mikekistler, @allenjzhang We need to be able to reference FHIR objects as external models. As for clients, FHIR as its own serializers, so it will be great if emitters can give the option to set (by decoration, custom configuration) specific serializers.

[asaflevi-ms]

BTW - "@useref for emitter to generate correct output which we currently support" I tried to use it and got "unknown decorator"

[bterlson]

I assume we are talking about Json Schema not OpenAPI here, and yeah useRef is not implemented there but should be. I'm not clear if this meets the "directly import" criteria in the OP though.

[bterlson]

it will be great if emitters can give the option to set (by decoration, custom configuration) specific serializers.

Can you give more detail here? I'm not sure I understand the scenario yet.

[mikekistler]

BTW - "@useref for emitter to generate correct output which we currently support" I tried to use it and got "unknown decorator"

You must import the @typespec/openapi3 package to use the @useRef decorator.

See this link for more information and a Playground example of using the @useRef decorator to get an external reference.

[asaflevi-ms]

@mikekistler Is it possible to import openapi3 and generate OpenAPI version 2 json spec ?

[mikekistler]

Yes ... for OpenAPI v2 you need to use the @azure-tools/typespec-autorest package.

Here's a playground example

[asaflevi-ms]

@mikekistler

OpenApi generated with an error

[mikekistler]

What extension/tooling is generating this error?

I think it is likely that whatever it is assumes that the $ref value is a "URL" -- that will actual resolve in an HTTP request.

I tried this same thing but using a true "URL" and I'm not getting an error:

[allenjzhang]

While this has been an epic to start with, it is now a design discussion on a feature request. Removing Epic label.