Right now, the term "property" is still overloaded. We generally refer to an entity property as property, but then the things contained in TypedData structures are also called properties. That results in some confusing methods in the property item classes, e.g. get() there takes a $property_name. It means the name of one of the item values, but having "property" in there makes one think of entity properties. In particular, as "entity properties" are the mental context, i.e. as a developer you are doing something with entity properties so in that context "property" let's you think of an "entity property".
That said, I think we should find another term for the things contained in data structures.
Comments
Comment #1
effulgentsia CreditAttribution: effulgentsia commentedI had also shared this concern up until last week. However, I looked around at what terminology other ORM systems use, and found oData to map most closely to our model. Quoting from http://www.odata.org/documentation/overview#EntityDataModel:
I'm currently leaning towards making TypedData API use the same terminology as oData's EDM: i.e., use "property" to refer to both properties of entities and properties of non-entity structures. Additional terminology changes that would bring TypedData closer to oData's EDM (at least to my understanding, correct me if I'm wrong):
Additionally, oData currently uses SimpleType and Primitive interchangeably, but there's a proposal to differentiate them to allow new "SimpleType"s (scalars) to be made by extending (but not composing) primitives. Even though this isn't part of the oData standard yet, I think the concept (and terminology) is something we might want in TypedData API.
Anyway, not sure if all this is appropriate for this issue. Please move it to other issues as you see fit, but what do you think about using oData terminology?
As a side note, there's also an oData PHP library, but it's geared towards mapping specific business object classes to the oData model rather than what TypedData API and EntityProperty API are doing, which is creating standardized data object interfaces and base classes. However, there might be some code there that's of interest to us.
Comment #2
fagoInteresting thanks, I think this comes pretty class to what we do here.
Yep, I agree it looks like it's more about mapping. A point that makes our implementation quite different I think is extensibility as we allow the extension of data types by implementing your own wrappers while oData don't. For oData that's obviously a nogo as they need a portable standard while we can leverage what PHP gives us.
I'm not sure that the comparison flies:
@Structures: The following oData sentence makes me think that our term fits quite good:
(with "key" meaning identifier in oData context).
So this makes me think we should improve our docs from
to
?
and the List interface docs
to
?
Yes, we already have with the possibility to define primitives that map to pre-defined primitives. So we use "primitives" like "SimpleType" and pre-defined primitives for the built-in ones. I think it's fine to go that way and don't use SimpleType as long as we do not use ComplexType as well. We could start use "ComplexType" for all non-primitives but I don't see much value added in introducing yet another term that people need to understand if we do not have an requirement and/or interface for it.
Comment #3
fagooh, set does not fit really as it may not contain duplicates, but we allow them. (Think of entity reference referencing the same node multiple times or on a multiple integer field having two times the same integer put in.)
Comment #4
fagoOK, I research commoned terms more using wikipedia.
So regarding the wikipedia data structure article though I think structure as the wrong term as well:
and
What completely does not map to a list being not a data structure. Even when writing this it makes no sense to me, ouch.
Yes, map or hash does not fit as it's not added and deleted freely. Record or struct would fit.
Note this sentence:
Whereas I find the usage of the term "element" there interesting as well as I was thinking about this one already. Field is a nogo, member - I'm not sure.
A further interesting wikipedia article is this one:
This table tells me that our usage of "List" fits perfectly.
Then most interesting, not the list starting with "Composite type":
Looks like this is fitting to our usage of "structures". The article reveals:
Oh, yes that's what we are doing. The rest of the article is mostly about "struct"s. So would composite type a term we could use? But composite type just describes the type not the interface :/ Or better just StructInterface?
Comment #5
fagohttp://en.wikipedia.org/wiki/Record_%28computer_science%29 says
Note "A record is a value that contains other values". So I think going back to ContainerInterface and container would be a good move.
Comment #6
fagoFortunately, more discussions and investigation revealed it turns out this is wrong. Lists are simple types as well, so we could go with "complex types" instead of structures.
What stays though is that
$entity->property instanceof ComplexTypInterface
does not really fit. ComplexDataInterface could be an option.
Also, the question remains how the elements contained in a ComplexTypInterface should be called. oData uses properties, xmlSchema uses elements as XML already uses elements.
Comment #7
effulgentsia CreditAttribution: effulgentsia commentedoData uses "element" to refer to items in a Collection, as distinct from "properties" which are *named* items within a ComplexType.
#4 and #5 are good resources, but the problem is, depending on which schema language, ORM, language compiler, DBMS, etc. system you look at, you find slightly different terminology for these very foundational data structuring concepts. So, I suggested that we find a particular system that most closely overlaps our problem space, and use its terminology, rather than mixing and matching from different places.
I continue to think that oData's EDM is the system that most closely overlaps what we're trying to do, so unless someone finds a better matched model, I'll keep pushing us to adopt its terminology where it makes sense, including using the word "property" for both named items within ComplexTypes and named items within Entities. Really, an Entity is just a ComplexType that also has a key/id.
Where oData falls short though is that it's more of a schema / mapping model, not a set of interfaces and base classes. So, when it comes to naming the interface (e.g., ComplexTypeInterface), the terminology might not feel quite right, as in
$node->body[0] instanceof ComplexTypInterface
might be awkward if we think of $node->body[0] as data that has a type, not data that is a type. This needs a bit more thought? Anyone with ideas on this?Comment #8
fagoI tend to think that doing interfaces like "ComplexTypeInterface" would be wrong. E.g. we've EntityInterface not EntityTypeInterface: So the class Node is an entity type, but the terms used to describe the classes and interfaces commonly refer to the instantiated nouns, not the types. That's why we use EntityInterface or StreamWrapperInterface, not StreamWrapperTypeInterface.
That said, I think we should find a term for the instance of a complex type and use that as interface name. ComplexDataInterface - it's data of a complex type.
I agree that from what I've seen oData's EDM data model most closely overlaps with what we are doing. Maybe we should just get used to referring to the "fid" of $node->field_image->fid as property of the image item *and* so differentiating the term property in general vs entity property as specially referring to the properties of an entity.
Yeah, that's why the EntityInterface will extend the StructureInterface or however it will be called :-)
Comment #9
dixon_I don't think we should differentiate the names of entity properties and properties contained in structures. It's an essential feature of the Typed Data API, that we rather should embrace, IMO. I think that's important.
Regarding renaming
StructureInterface
, I don't see the point of semi-adopting the oData terminology since we are not using oData. I thinkStructureInterface
is pretty clear already, and don't see an immediate need of renaming it.I agree with the discussions we had at DrupalCon, I'm in favor of staying with
ListInterface
. It's important to make it clear it's not a structure.Comment #10
fago@StructureInterface:
yeah, but at DrupalCon concerns were already raised that StructureInterface sounds like it includes Lists as well. After researching wikipedia - see #4 - I have to agree with that : StructureInterface sounds like data structures what would include Lists. The c "struct" is really the only thing that matches, but that's "struct" not structure. I really think we should rename it to avoid confusions here.
Regarding Collection vs List I could see Collection to be a possible way to go also, but I also think that List is clearer. It had was clear in discussions at Drupalcon also and according to the definitions on wikipedia it's exactly what we are talking about: an ordered non-unique list of things (possibly containing duplicates).
Comment #11
fagoAs discussed during the skype call, we want to go with the following terms for now:
TypedDataInterface and TypedData( no base)
ComplexdataInterface
ListInterface
Comment #12
fagoFor the term "property" we concluded that going with this makes sense as this is what oData and others use as well. So we have ComplexData containing properties, such as an entity that contains properties.
Comment #13
fagoImplemented and pushed to entity-property. I've not renamed drupal_wrap_data() yet as this will go away while doing #1732724: Implement data types as plugins. anyway.