An enumeration of this package states itself two ways : the bare constant, when there is nothing more to say, and the member class, when there is — a status carrying the reason it was set. Stored and read back, the second form is a plain array, and turning it into the member class again is the same walk for every enumeration : hence one function rather than one per family.

The member is read from the payload in this order :

• additionalType, the URI every member states of itself since 1.5.0 — the same string the bare constant carries, so both forms filter alike ;
• @type, which carries the short name of the class (EventCancelled), never the URI — that is what the serialization writes, and what a payload written before additionalType existed carries alone.

⚠️ The two keys do not say the same thing, which is why both are read : a vocabulary is free to spell its URIs otherwise than its class names — AppointmentStatus spells …#NoShow where the class is AppointmentNoShow — so neither key can be derived from the other.

When nothing is recognized, $default is answered : the enumeration head itself, so an unknown status keeps the reason it carried rather than being dropped.

Anything that is not an array is handed back untouched — a lone PropertyValue is a legal shape of the additionalProperty property, and this helper is not the place to reject it. An array that is not an indexed, non-empty list yields null, so a caller can tell "nothing to hydrate" from a result.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.

Anything that is not an array is handed back untouched — a lone ContactPoint or an unresolved string reference are legal shapes of the contactPoint property, and this helper is not the place to reject them. An array that is not an indexed, non-empty list yields null, so a caller can tell "nothing to hydrate" from a result.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.

Handles both single DefinedTerm array and array of DefinedTerm.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.

A status is written one of two ways : the bare constant, when there is nothing more to say, or the member class, when there is — new EventCancelled([ 'description' => '…' ]) says why an event was called off, and a string cannot. Stored and read back, the second form comes back as a plain array like any other object, and this helper turns it into the member class again.

🔑 The bare constant comes back untouched. It is not an array, so it falls through the first guard — which is the whole point : a consumer must be able to hand this helper whichever form was stored without knowing which one it was.

The member is resolved by findEnumerationMember(), from the payload's additionalType — the URI every member states of itself since 1.5.0 — then from its @type, which carries the short name. Nothing recognized gives an EventStatusType : the status is unknown to this vocabulary, and answering null would throw away the reason it carried.

⚠️ A status is single-valued. An indexed array is still read as a list, for consistency with the rest of the family, and answers null when nothing in it resolves.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.

Handles both single GeoCoordinates array and array of GeoCoordinates.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.

The two offer helpers this package already carries answer narrower questions : hydrateOfferPurchase() only ever builds an OfferForPurchase, and hydrateAggregateOffer() an aggregate. A plain Offer — what Organization::$makesOffer carries, and with it every property that lists bare offers — had none.

Handles both a single offer array and an array of offers. The offer itself is built through Reflection::hydrate(), which honors the #[HydrateAs] attributes the class declares — eligibleQuantity comes out a QuantitativeValue, priceSpecification a PriceSpecification, its union naming a single class that reflection resolves on its own.

itemOffered is the exception : its CreativeWork|Event|Product|Service union cannot be resolved from the property type alone, so the target class is read from the payload's JSON-LD @type, exactly as hydrateDocumentLineItem() does for a document line :

• a @type ending with Service (e.g. Service, FoodService) gives a Service ;
• anything else gives $productClass.

🔑 $productClass is what keeps this helper in org\schema. The commerce-enriched product of this package lives in xyz\oihana\schema\products and org knows nothing of xyz — so the default is the plain Schema.org Product, and a caller on the business side passes its own, as long as it stays a subclass so the declared union still holds.

Anything that is not an array — an unresolved string reference, an already typed instance — is left untouched.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.

Organization|Person is a common Schema.org union (e.g. Order::$customer, Order::$seller, Invoice::$broker/$provider, Event::$funder...) that Reflection::hydrate() cannot resolve from the property type alone : the declared union always resolves to its first class member, so a Person payload silently comes out as an (empty-ish) Organization. This helper reads the payload's JSON-LD @type instead : Person gives a Person (or $personClass), anything else — Organization itself, or one of its many subtypes (Corporation, LocalBusiness, GovernmentOrganization...) — gives an Organization (or $organizationClass), which stays the safe default when @type is absent or unrecognized.

$organizationClass/$personClass let a caller pin the target to a business subtype instead of the plain Schema.org class — e.g. xyz\oihana\schema\organizations\Customer (extends Organization) or xyz\oihana\schema\people\CustomerEmployee (extends Person) — as long as each stays a subclass of the type it replaces, so the property's declared union type still holds.

Handles both a single definition and an indexed list of definitions.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.

Handles both single PostalAddress array and array of PostalAddress.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.