Describe what you need on Dataset
Describe what you need on DataDownload

Open separate issues for those 2 needs, so that the whole community can help you further.

I volontary proposed this change on Thing and not Dataset or DataDownload, because this is not the first time I tried to use it on something else.
In fact, I need it on Organization and Person too. I already needed it on other classes too.

Thing is the only common abstract ancestor which is already holding all generic properties. This is why it seems logical (to me) that additionalProperty is a Thing property.

(I also have some specifics on Dataset and DataDownload and will submit 2 other separates issues).

What I was pretty amazed at when first learning about schema.org / JSON-LD is how restrictive the schema is towards custom / unknown properties. Why do we even need additionalProperty?

There is additionalType which makes some sense. You create additional schemas to support custom properties. Create a more specific type that has your custom properties, specify it in a schema and then use additionalType to add those properties to whichever object. However, the problem here is the overhead it gives. Creating a custom schema is a lot of work.

Why not just ignore unknown fields??

I understand it could give collisions later on when fields with the same name are added to the spec, but that could be easily solved with a naming convention (e.g. custom property names should start with an underscore).

Imho, the way it currently works, makes schema.org much less flexible a tool for many purposes. For example I investigated using schema.org entity types as the model for a web api, but the problem I run into is that adding custom properties is either ugly / impossible (as this issue demonstrates) via additionalProperty or just way to much work (via additionalType). I would like it MUCH more if the default behavior would just be to ignore unknown fields.

To be clear, additional property is a pretty weak approach in the sense that it handles very well the case where we don't really know what the properties are. This is common in ecommerce, where a site might have foo=bar, xyz=1000, or for geo/place, things like horse=true.

Aside from these you can always mix in other vocabularies, regardless of whether they are presented as "extensions" (like gs1.org/voc) to Schema.org or not. Whether search engine features make much use of these is beyond schema.org's remit, but the data structure is perfectly sensible and useful. So as @mfhepp says, we shouldn't encourage over-use of additionalProperty when normal properties from nearby vocabularies can be used instead.

I think using additionalProperty won't encourage schema-less attributes because if I use schema.org/JSON-LD this is because I want structured data.

I don't see additionalProperty as a replacement to strong typed properties but as complementary solution:

• don't hide/loose data just because a property has not yet been standardized on schema.org
• handle free key-values store on models
• allows to detect properties to be typed and to become candidate to be officially part of a domain class.

I think would be easier to detect a recurrent additionalProperty and submit a model evolution proposal.

Plus, I've been looking into issues, and a recurrent response is: "You should use additionalProperty for this but this is not available on this class":

• Documentation for 'additionalProperty' is lacking. schemaorg#1685
• How to extend the property of existing "type" or "class" schemaorg#1505
• How to record a 11179 data element (aka. variable)? schemaorg#1386
• Extension Proposal: Brand schemaorg#948
• ...
  There is also multiple requests/proposals on different domain models to add additionalPropery

Ping @rvguha - what do you think?

I second this proposal. Furthermore, https://schema.org/additionalProperty claims it applies to QualitativeValue and QuantitativeValue. But none of the examples shows such use.

• Example 3 shows "Grouping and Hierarchical Order of Properties" but the link is value not additionalProperty https://github.com/schemaorg/schemaorg/issues/2145
• So listing QualitativeValue and QuantitativeValue in domainIncludes is confusing and misleading. (At least I couldn't think of any actual example)

Are there remaining issues to discuss here?

No, I think we can simply go forward.

As I was the original designer of this proposal, I would like to explain the motivation a bit:

There are many cases where publishers of data have identifiers for clearly defined properties. This can be either properties applied to all products in a shop, or properties from external standards like eCl@ss.

For those properties, we at least have a site-specific unique name or even a globally unique identifier from the external standard.

additionalProperty allows publishers to expose as much data semantics as they reasonably can without imposing a lot of additional barriers. This is better than a black or white approach where the property is either in schema.org or not supported.

The full rationale is described here: https://www.w3.org/wiki/WebSchemas/PropertyValuePairs

Agree with @rvguha here.

Schema.org is not a closed system, you can always add additional properties from other vocabularies when they're missing in schema.org.

It would be better to encourage that practice than to add an extra layer of indirection. The case of Product is reasonably special, aggregators do have useful property/value pairs that they barely understand. But we added a health warning into PropertyValue for good reason...

Always use specific schema.org properties when a) they exist and b) you can populate them. Using PropertyValue as a substitute will typically not trigger the same effect as using the original, specific property.

To advocate for this, there is some benefit to allowing developers to use https://schema.org/additionalProperty for experimenting before they get the schema correct.

As examples, there was some discussion in issue schemaorg/schemaorg#561 about the language at the other end of https://schema.org/EntryPoint. I would not say we have an answer yet, but using additionalProperty in WatchAction links has allowed some experimentation in the sorts of parameters a data reader might want. I still hope we can codify a good pattern for structuring this data.

Similarly, Google once used additionalProperty to understand JobPostings but once the space was clearer, worked with the community to adopt https://schema.org/jobLocationType.

I would not expect any reader to understand all uses of additionalProperty, but there are times like @mfhepp suggests where some data is better than none, particularly when exploring areas where authors have not previously provided structured data.

See issue #7 for the context of the move from the main Schema.org issue tracker to this repository.