Class: Edoxen::EntityRef

Inherits:
Lutaml::Model::Serializable
  • Object
show all
Defined in:
lib/edoxen/entity_ref.rb

Overview

EntityRef — a typed cross-reference between entities (v2.1, TODO.refactor/44).

Single identity: exactly one of urn, identifier, or local_ref must be set. Optional metadata: kind, role, note.

Encapsulation:

- Read the identity via `#resolved_identity` (returns the canonical
form — URN string, StructuredIdentifier, or local key).
- Validate via `#valid?` (true when exactly one identity field is
set; `#multiple_identities?` flags the rare ambiguous case).

Pilot: Motion.resulting_decision_ref (parallel to the existing resulting_decision: String). v3.0 will remove the String form.

Instance Method Summary collapse

Instance Method Details

#multiple_identities? ⇒ Boolean

True when two or more identity fields are set. Useful for migration tooling that wants to warn on ambiguity without rejecting outright.

Returns:

  • (Boolean) 


36
37
38
 
# File 'lib/edoxen/entity_ref.rb', line 36

def multiple_identities?
  identities_set.size > 1
end

#resolved_identity ⇒ Object

Returns the canonical identity (URN > identifier > local_ref precedence). Callers that need a single value should validate first via #valid?; on a multiple-identity ref the precedence is still applied but the data is suspect.



44
45
46
47
48
49
50
 
# File 'lib/edoxen/entity_ref.rb', line 44

def resolved_identity
  return urn if urn && !urn.to_s.empty?
  return identifier if identifier
  return local_ref if local_ref && !local_ref.to_s.empty?

  nil
end

#to_s ⇒ Object 



52
53
54
55
56
57
58
59
60
 
# File 'lib/edoxen/entity_ref.rb', line 52

def to_s
  identity = resolved_identity
  return "(invalid EntityRef)" unless identity

  case identity
  when StructuredIdentifier then "#{identity.prefix}/#{identity.number}"
  else identity.to_s
  end
end

#valid? ⇒ Boolean

True when exactly one identity field is set. The wire contract (TODO.refactor/44 + JSON-Schema) is XOR: setting 0 or ≥2 identity fields is a data error.

Returns:

  • (Boolean) 


29
30
31
 
# File 'lib/edoxen/entity_ref.rb', line 29

def valid?
  identities_set.size == 1
end