[discussion]: `Descriptor` vs `properties`

[signekb]

Description

I think we need to be clearer on what we mean when we say descriptor and property/properties. I must say that I also find the distinction from the DataPackage standard confusing. Especially the fact that there are four descriptors and the rest are properties (DataPackage, DataResource, TableDialect, and TableSchema, respectively). I guess they have "chosen" these four to be descriptors bc they are the most essential ones in terms of describing the data itself?

Maybe you understand this distinction better, @martonvago ?
I've actually also asked about this distinction on the Frictionless Data Slack now.

Currently, our design docs include this definition:

Object	Description
descriptor	The standalone and complete metadata structure contained in a JSON file, for example, in datapackage.json.
properties	Individual elements of the metadata structure or the structure as a whole.

For me, it becomes unclear/the definitions bleed into each other, with the last part of the properties description "or the structure as a whole".

One way we could simplify this (without also having to rename anything in Sprout to keep consistency) would be to say that we only refer to descriptors as the content of the datapackage.json file.

That definition could look something like this:

Object	Description
descriptor	A standalone and complete metadata structure (a JSON object) contained in a JSON file, such as datapackage.json, or loaded as a Python dictionary
property/properties	Individual attribute(s) or metadata field(s), name-value pairs, of a descriptor, including nested properties.

This way, whenever we load everything from the datapackage.json file in a dict it's the descriptor, while every subpart of it is referred to as properties. This is, however, not completely aligned with the DataPackage specification.

Another alternative would be to completely ignore the term "descriptor" and use properties for everything, as we've done so far.

What do you think?

[martonvago]

I think your understanding is correct!

As far as I understand, it's a descriptor if it has its own JSON schema file and can live in its own JSON file. So we have data-package-schema.json and datapackage.json based on that. But we could have data-resource-schema.json and dataresource.json based on that. So I guess they defined schemas only for the 4 big ones that can potentially stand alone -- which makes sense.

I think we're using "properties" in two ways:

1. = Loosely, just a bag of values. So the descriptor as a whole (as a JSON file or as a dict) is a collection of properties -- the properties describing the package.
2. = In more technical language, a set of key-value pairs. So a dict consists of properties. And, since a value can be a dict, properties can contain properties.

If you'd prefer to avoid # 1, that's fine by me!

[lwjohnst86]

Yea, I'm also very confused about the terms and why they are even necessary to have, like what communication purpose do they serve. I think I agree with what you propose tho, as with @martonvago number 2 suggestion and avoiding number 1.

Not sure if we should change the language in Sprout tho...