-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Usage of field
vs property
#2660
Comments
From the TDC discussion, we should make efforts to remove unnecessary ambiguity when using words such as keyword, property, attribute and field. Can we limit terms to just object, property, map and array? /cc @webron Can we get your insight on why |
I think there's a case to be made that we should reserve "property" for a subschema of an object schema: a subschema that defines valid members for a conforming object ("members" as defined by RFC 8259). To illustrate this distinction, we could say the "Member" seems a little esoteric to me, but if we defined "field" to also refer to a literal key-value pair in a JSON object, then we could say:
But there are some confusing subtleties to this for sure. One of them would be that the Edit: this certainly isn't how JSON Schema constrains the use of "property":
(Source: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-6.5.3) |
My comment is beyond the scope of this specific issue but wanted to add another relationship to modeling taxonomy. In travel we use a shared domain model (Open Travel 2.) to describe business objects such as reservation, invoice, fare, guest/passenger and others. We as a community created a modeling tool and complier to take the model and create XSD and swagger files. Hence we have one definition of a service but can expose as either XML or JSON. Our (open source) complier takes the model, expressed itself in XML, and converts it. For swagger we already have to do some mapping. My point being how business objects are defined via various modeling approaches is affected by changes to OAS. It would be helpful to keep an eye on how business objects are defined (see #hudlow comment above) and not make it needlessly difficult to map them. |
@OAI/tsc review request: Do we want to try to tackle this in the patch releases or punt it to 3.2 or Moonwalk? |
That may depend on what we agree on, and how much time we want to spend finding agreement 😎 Current statistics in 3.1.0
Consistent use of "field" instead of "property" would be the less invasive change, and I'd be fine with doing it in patch versions. |
What Ralf said but I don't want to hold the patch releases for it. Let's aim for 3.2 and consider any other wording changes that should be part of the mission? |
Already fixed in 3.0.4 and 3.1.1 |
@ralfhandl can we close this now? |
I was wondering if authors of the spec would be open to make usage of
field
andproperty
somehow consistent. When we have specification objects we refer to it's properties as fields, either fixed one, patterned one or mapped one. Then in field descriptions we refer to those fields as properties.Is there a semantic difference between field and property wording or some additional distinction between
field
vsproperty
?The text was updated successfully, but these errors were encountered: