Symbol API fields answer differently from GetElementProperties, with no sign that the answer is incomplete

Start by reading the Symbol API implementations for kind, type_facts, specializations, and parameter direction, then compare them with the GetElementProperties path and the four reproduction cases in the issue. Run the two named Python suites, opensysml-py and opensysml-py-props, to confirm the discrepancies. Done means the chosen fix or documentation makes the Symbol answers consistent with, or clearly identifies their limits relative to, the metamodel values.

This issue was written with AI help. The reproduction was run against the version below.

Since #2013, the same question can be asked of the Symbol API and of GetElementProperties, and the two sometimes disagree. When the Symbol API has no field for something, a user can tell and looks elsewhere. The problem is the fields that do exist and give a wrong or partial answer without saying so: a user who starts from Symbol has no reason to suspect the value and no pointer to element_properties.

We compared both surfaces on the 1630 cases of our suite (opensysml-py and opensysml-py-props). 470 reads are answered only by GetElementProperties because the Symbol API has no field for them, which is fine. In 37 further cases, a dedicated Symbol field answers and GetElementProperties gives the value the Pilot gives. The four patterns are below.

Reproduction

package P {
    private import ScalarValues::*;
    port def AP { out item a; }
    part def T;
    part def Vehicle { attribute plain : Real; }
    part tuned : Vehicle { attribute :>> plain = 3.5; }
    part def Owner {
        part q : T;
        part pSub :> q;
        ref part pRef ::> q;
    }
    action def Supervise {
        port alarmPort : AP;
        item alarm;
        action sendVia send alarm via alarmPort;
    }
    requirement def Req {
        subject s : Part;
        in x : Real;
    }
}

m = opensysml.loads(SRC)
def props(el, *names):
    r = m.element_properties(el, *names)
    return {p.name: [str(v) for v in p.values] for p in r}, r.element.metaclass

1. Symbol.kind flattens action kinds.

m.get("P::Supervise::sendVia").kind              # 'actionUsage'
props("P::Supervise::sendVia", "name")[1]        # 'SendActionUsage'

The same happens for accept, assignment and perform actions (15 cases). The if, while and for actions are wrong on both surfaces (#1985).

2. Symbol.type_facts is empty where the feature has a type.

m.get("P::tuned::plain").type_facts.resolved_id  # ''
props("P::tuned::plain", "type")[0]["type"]      # ['ScalarValues::Real']
m.get("P::Owner::pSub").type_facts.resolved_id   # ''
props("P::Owner::pSub", "type")[0]["type"]       # ['P::T']

In each case the type is inherited from the feature that is redefined (:>> plain), subsetted (:> q) or reference-subsetted (::> q), and the feature declares none of its own (12 cases).

3. Symbol.specializations leaves out a reference subsetting.

[(sp.kind, sp.target_id) for sp in m.get("P::Owner::pRef").specializations]   # []
# element_properties("P::Owner::pRef", "ownedSpecialization") -> one ReferenceSubsetting (to P::Owner::q)

The references specialization kind exists, but ref part pRef ::> q does not produce one (6 cases).

4. The subject of a requirement def has no direction in the Symbol listings.

# children() + members(inherited=True, library=True) of P::Req that carry metadata["direction"]:
#   [['in', 'x'], ['out', 'result']]
props("P::Req", "directedFeature")[0]["directedFeature"]
#   ['P::Req::s', 'P::Req::x', 'Requirements::RequirementConstraintCheck::result']
props("P::Req", "subjectParameter")[0]["subjectParameter"]   # ['P::Req::s']

The subject s is an in parameter, but the Symbol API lists it without a direction, so a client that collects parameters by direction misses it (4 cases: requirement and use case defs).

Beyond these 37, there are 108 more where the Symbol API gives an empty listing rather than "unknown": a connector's ends are not among its children (endCount 0), and a #M or @M; annotation is not a child. We count those separately because they depend on where a client looks for ends and annotations.

Suggestion

Any of these would help, from least to most work:

1. Document on each overlapping Symbol field (kind, type_facts, specializations, metadata["direction"]) that it is a summary, and point to element_properties for the value the specification defines.
2. Delegate. Derive these fields from the same metamodel evaluation that GetElementProperties serves, so the two surfaces cannot disagree. attributes() delegating to members (#1974) is a precedent.
3. Mark incompleteness in the answer where a field is known to be partial, as withheld_library_members does for the member listing, rather than answering an empty string or an empty list.

Version

• OpenSysML develop at 19bc16d1df (nightly-199-g19bc16d1df), bin/sysml-grpc built with make build-grpc
• Python client from client/python of the same commit
• Suite: https://github.com/hideo67/sysmlv2-tests, suites opensysml-py (test_matrices.py) and opensysml-py-props (test_props.py); per-case results in test-suite/report-all-SNAPSHOT.md