Repository navigation
Usage of field vs property #2660
Description
I was wondering if authors of the spec would be open to make usage of field and property 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 vs property?
Activity
darrelmiller commentedon Jul 29, 2021
From the TDC discussion, we should make efforts to remove unnecessary ambiguity when using words such as keyword, property, attribute and field.
Can we clarify when each of those terms should be used?
Can we have a generic meta model for the OpenAPI document that connects terms to externally referenced terms?
Can we limit terms to just object, property, map and array? /cc @webron Can we get your insight on why
fieldwas used?hudlow commentedon Jul 29, 2021
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
Petschema contains aidproperty even though we know the literalPetschema object in an OpenAPI definition file won't have a member namedid. Rather it will have a member namedpropertieswhich has a member namedid."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:
Petschema contains anidproperty."Petschema object contains apropertiesfield."idfield in conformance with thePetschema."idfield within thepropertiesfield of thePetschema object defines anidproperty for thePetschema."But there are some confusing subtleties to this for sure. One of them would be that the
requiredarray would really refer to required fields. (In other words, I'm not sure "required properties" makes sense if properties are schemas for fields.)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)
swaldron58 commentedon Jul 29, 2021
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.
handrews commentedon May 27, 2024
@OAI/tsc review request: Do we want to try to tackle this in the patch releases or punt it to 3.2 or Moonwalk?
ralfhandl commentedon May 28, 2024
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.
lornajane commentedon Jun 4, 2024
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?
ralfhandl commentedon Aug 30, 2024
Already fixed in 3.0.4 and 3.1.1
lornajane commentedon Nov 4, 2024
@ralfhandl can we close this now?