Re: [httpapi] RFC 9512 on YAML Media Type

Inline:

On Mon, Feb 19, 2024 at 8:40 AM Roberto Polli <robipolli@gmail.com> wrote:

> Hi Orie.
>
> On Mon, 19 Feb 2024 at 15:11, Orie Steele <orie@transmute.industries>
> wrote:
> > Congratulations to all involved.
>
> Thanks :)
>
> > I've seen the structured suffix already being used here:
> >
> >
> https://www.w3.org/community/reports/json-ld/CG-FINAL-yaml-ld-20231206/#application-ld-yaml
> >
> Yes, the YAML-ld concept started under the IETF but was then delegated
> to the json-ld wg.
>
> > Not sure if I am interpreting the API media type comment correctly... Is
> there a plan to do
> >
> > application/schema+json
> We're working on it. See
> https://github.com/ietf-wg-httpapi/mediatypes/issues
>
>
> > application/schema+yaml
> While I think it's key, we should first finish schema+json
>
>
> > In a single document?
>

>
> Can you please clarify what does "single document" mean?
> A document should be either YAML or JSON.
> You can use YAML "flow collection style", in order to create
> JSON-like YAML. See
> https://www.rfc-editor.org/rfc/rfc9512.html#section-3.4
> Still, the content will be either JSON or YAML.
>

Agreed, I meant that similar to how https://swagger.io/specification/
includes the following comment:

"An OpenAPI document that conforms to the OpenAPI Specification is itself a
JSON object, which may be represented either in JSON or YAML format."

If a document registers media types for OAS (as opposed to vanilla YAML, or
vanilla JSON Schema) we might see a sentence like:

Representations of an OpenAPI Specification *schema* SHOULD use
"application/schema+json" and MAY use "application/schema+yaml", and then
explain why YAML is a may or why it is reversed (yaml recommended over
JSON).

https://github.com/ietf-wg-httpapi/mediatypes/issues/18

FWIW, we've experimented exposing OAS and enabling content type negotiation
with the accept header.
Our use case was to support YAML and JSON schema for constraining JSON-LD
based digital credentials, per:

https://w3c.github.io/vc-json-schema/#representations-of-json-schema

Recently, YAML has been used to support "selective disclosure" in SD-JWT:
https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/
https://github.com/openwallet-foundation-labs/sd-jwt-python/blob/main/examples/w3c-vc_for_slide_deck/specification.yml

The same approach is also explored in:
https://datatracker.ietf.org/doc/draft-prorock-cose-sd-cwt/
https://github.com/transmute-industries/sd-cwt/blob/main/test/sd-cwt/testcases/scitt-example/spec.yaml

TLDR, I see a lot of use cases for yaml based claimsets (with disclosure
annotations) and yaml based credential schemas (JSON Schemas in YAML).

We've been serving YAML based JSON Schemas for Supply Chain oriented
digital credentials in this CG work item:

https://w3c-ccg.github.io/traceability-vocab/#open-api
https://w3c-ccg.github.io/traceability-vocab/openapi/#get-/schemas/common/AgricultureInspectionGeneric.yml

We would like to be able to negotiate for a given "credential schema" like
this:

GET https://vendor.example/schema/credential-type/v1 --accept
application/schema+yaml or application/schema+json

If there is a strong reason NOT to do this, critical feedback is also
appreciated.

Thanks again for your kind words,
> R.
>
>
> > On Mon, Feb 19, 2024 at 3:35 AM Roberto Polli <robipolli@gmail.com>
> wrote:
> >>
> >> Hi Darrel + Rich,
> >>
> >> On Mon, 19 Feb 2024 at 04:48, Darrel Miller <darrel@tavis.ca> wrote:
> >> > Congratulations to Roberto, Erik and Eemeli on getting over the
> finish line with RFC 9512.  It was great to see the deep thinking that went
> into getting this document as clear and as comprehensive as possible.  I am
> confident that the time spent on getting this document right will save many
> people from frustration in the future.
> >>
> >> Thanks to you  Rich and all the wonderful IETF, YAML, OAS and
> >> JSONSCHEMA communities that make it happen.
> >>
> >> The road to API mediatype standardization is still long, though :D
> >>
> >> Have a nice day,
> >> R.
> >>
> >>
> >> > ________________________________
> >> > From: httpapi <httpapi-bounces@ietf.org> on behalf of
> rfc-editor@rfc-editor.org <rfc-editor@rfc-editor.org>
> >> > Sent: Wednesday, February 14, 2024 5:01 PM
> >> > To: ietf-announce@ietf.org <ietf-announce@ietf.org>;
> rfc-dist@rfc-editor.org <rfc-dist@rfc-editor.org>
> >> > Cc: rfc-editor@rfc-editor.org <rfc-editor@rfc-editor.org>;
> drafts-update-ref@iana.org <drafts-update-ref@iana.org>; httpapi@ietf.org
> <httpapi@ietf.org>
> >> > Subject: [httpapi] RFC 9512 on YAML Media Type
> >> >
> >> > A new Request for Comments is now available in online RFC libraries.
> >> >
> >> >
> >> >         RFC 9512
> >> >
> >> >         Title:      YAML Media Type
> >> >         Author:     R. Polli,
> >> >                     E. Wilde,
> >> >                     E. Aro
> >> >         Status:     Informational
> >> >         Stream:     IETF
> >> >         Date:       February 2024
> >> >         Mailbox:    robipolli@gmail.com,
> >> >                     erik.wilde@dret.net,
> >> >                     eemeli@gmail.com
> >> >         Pages:      13
> >> >         Updates/Obsoletes/SeeAlso:   None
> >> >
> >> >         I-D Tag:    draft-ietf-httpapi-yaml-mediatypes-10.txt
> >> >
> >> >         URL:        https://www.rfc-editor.org/info/rfc9512
> >> >
> >> >         DOI:        10.17487/RFC9512
> >> >
> >> > This document registers the application/yaml media type and the +yaml
> >> > structured syntax suffix with IANA.  Both identify document
> >> > components that are serialized according to the YAML specification.
> >> >
> >> > This document is a product of the Building Blocks for HTTP APIs
> Working Group of the IETF.
> >> >
> >> >
> >> > INFORMATIONAL: This memo provides information for the Internet
> community.
> >> > It does not specify an Internet standard of any kind. Distribution of
> >> > this memo is unlimited.
> >> >
> >> > This announcement is sent to the IETF-Announce and rfc-dist lists.
> >> > To subscribe or unsubscribe, see
> >> >   https://www.ietf.org/mailman/listinfo/ietf-announce
> >> >   https://mailman.rfc-editor.org/mailman/listinfo/rfc-dist
> >> >
> >> > For searching the RFC series, see https://www.rfc-editor.org/search
> >> > For downloading RFCs, see https://www.rfc-editor.org/retrieve/bulk
> >> >
> >> > Requests for special distribution should be addressed to either the
> >> > author of the RFC in question, or to rfc-editor@rfc-editor.org.
> Unless
> >> > specifically noted otherwise on the RFC itself, all RFCs are for
> >> > unlimited distribution.
> >> >
> >> >
> >> > The RFC Editor Team
> >> > Association Management Solutions, LLC
> >> >
> >> >
> >> > --
> >> > httpapi mailing list
> >> > httpapi@ietf.org
> >> > https://www.ietf.org/mailman/listinfo/httpapi
> >>
> >> --
> >> httpapi mailing list
> >> httpapi@ietf.org
> >> https://www.ietf.org/mailman/listinfo/httpapi
> >
> >
> >
> > --
> >
> >
> > ORIE STEELE
> > Chief Technology Officer
> > www.transmute.industries
> >
> >
>

-- 

ORIE STEELE
Chief Technology Officer
www.transmute.industries

<https://transmute.industries>