Usage of `field` vs `property`

[char0n]

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?

[darrelmiller]

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 field was used?

[hudlow]

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 Pet schema contains a id property even though we know the literal Pet schema object in an OpenAPI definition file won't have a member named id. Rather it will have a member named properties which has a member named id.

"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:

• "The Pet schema contains an id property."
• "The Pet schema object contains a properties field."
• "The pet object contains an id field in conformance with the Pet schema."
• "The id field within the properties field of the Pet schema object defines an id property for the Pet schema."

But there are some confusing subtleties to this for sure. One of them would be that the required array 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":

An object instance is valid against this keyword if every item in the array is the name of a property in the instance.

(Source: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-6.5.3)

[swaldron58]

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]

@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]

@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

• 169 occurrences of "field"
  • 30 of them in section headings
• 129 occurrences of "property" or "properties"
  • 2 of them in section headings

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]

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]

Already fixed in 3.0.4 and 3.1.1

[lornajane]

@ralfhandl can we close this now?