Managing "Any of" use cases

[RobertJCarroll]

For any_of, we have several major use cases:

1. To define multiple enumeration options, eg, an expected list and an "unknown" list.
2. To define an "example" enumeration.
3. To define id types (for global id definitions)

LinkML describes the process as layering the any_of as additional requirements on top of the range: Any. This works in some cases, but in some export models it treats the Any as a real class and ignores the any_of. The documentation also says "Any or X or Y", which isn't consistent with the described intent- it must be only X or Y. They pydantic model appears to support the any_of, but the python model does not- it includes Any which means anything will pass validation as it's not defining the type limitations.

Our desired state is that the range: Any is completely ignored when the any_of ranges are present- it should appear in no output, including the documentation. All generated artifacts treat the slot as permitting only and everything in the any_of ranges. The pydantic model appears to have this behavior today.

For implementation examples:
1: Subject type, which must be EnumSubjectType or EnumUnknownOther.
2: Organism type, which can be any uriorcurie, but we include EnumOrganism with Human and Mouse for reference.
3: Subject Assertion Global ids, which includes 3 global id types.

[RobertJCarroll]

For our use cases, I propose the following items:

A, The range of the slot should be the "expected base type", ie, the type that all values will meet.
B. The any_of list must include ALL valid options.
C. We alter the documentation output class pages to omit the "expected base type" range. The display for a given field will then show only the list of explicitly defined any_of options.
The red parts indicate the range of the slot that should be excluded from the output, leaving only the any_of list.

Use case 1:

subject_type:
  range: Concept
  any_of:
    - range: EnumSubjectType
    - range: EnumUnknownOther

Use case 2:

organism_type:
  range: uriorcurie
  any_of:
    - range: uriorcurie
    - range: EnumOrganism

Use case 3:

assertion_id:
  range: string
  any_of:
  - range: obGlobalID
  - range: deGlobalID
  - range: msGlobalID

Longer text details:
Re A: For well-defined enumerations (1 and sometimes 2 above), this should be Concept as every answer should be in the Concept table. For cases where the provided values may not be present in our Vocabulary (sometimes 2 above), this should be uriorcurie as it allows any source. For id types or other similar cases (3 above), it should be string. This is how "poor performing" generators will list the type, so it should be helpful and consistent with the truly specified types. This also is what gets shown in the documentation slot "foreign key reference"- if it's Concept it will link to the concept table. This point is ONLY to attempt to work around the incorrect/inconsistent behavior of the generators. Unfortunately, if we restrict this to the "base enumeration" in use case 1 above, it will cause validation errors in the python model used in testing AND will show a foreign key to the enum which won't include the unknown options.
Re B: For 1 above, that means each allowable enum. For 2 above, it must include Concept or uriorcurie as well as the desired example enumerations. This enables clarity on what's actually permitted and what isn't.

[RobertJCarroll]

There is more that could be done, but I think this is ok for now and gives us a reasonable mix of specificity and flexibility.

The alternate proposal would be:

The range of the slot should be the "preferred type". For example, The subject_type would have range: EnumSubjectType. This will make some generators be too specific, ie, terms from EnumUnknownOther would fail some tests incorrectly. The documentation's diagrams will also lean towards too specific as well. If there is no "preferred type", eg, some of use case 2 and 3, we would use the "expected base type".

The other approaches would still apply.

Use case 1:

subject_type:
  range: EnumSubjectType
  any_of:
    - range: EnumSubjectType
    - range: EnumUnknownOther

Use case 2:

organism_type:
  range: EnumOrganism
  any_of:
    - range: uriorcurie
    - range: EnumOrganism

Use case 3:

assertion_id:
  range: obGlobalID
  any_of:
  - range: obGlobalID
  - range: deGlobalID
  - range: msGlobalID