Clarify 'processing' (dereferencing) nested descriptor chains

[fosdev]

https://github.com/alps-io/spec/blob/master/draft-00/draft-00.txt#L677-L681

We need to develop some guidelines about what this 'process' is. If I inherit properties from other profiles, I must in some fashion dereference the profile to find out which ones I have inherited. E.g. I am trying to resolve some attribute out of the profile of a response but it exists in the definition of a composed profile. Unless I first either completely dereference the 'href' profiles, or have some direction on how I hunt through those 'hrefs', it is not clear how I can find the meaning of things in composed profiles.

We discussed crawling into hrefs, but I feel that for a machine client to be able to completely dereference a profile, cache that response and then be able to xpath it or whatever will be simpler.

I think we need to expound how a machine would use ALPS and find the meaning of something as part of this discussion.

Also, this can be an issue w/r to how one would use a local href like:

<alps>
  <descriptor id="contact" type="semantic">
    <descriptor href="fname"/>
  </descriptor>
  <descriptor id="fname" type="semantic"/>
</alps>

What does it mean to deference here to find out the structure of a contact in XML (see https://github.com/alps-io/spec/issues/6) and maintain a unique id. Depending on the definition of processing/dereferencing you would have two 'fname' ids in the deref'd profile.

[fosdev]

Spec does not dictate you MUST dereference, but if you do completely dereference a profile, how should you do it.

[mamund]

Is this a scoping issue?

[mamund]

@fosdev: I am considering putting this off until after the first I-D draft at the end of February.

I still want to explore/resolve this but would like to get a first I-D published first.

If this is a problem, let me know.

[fosdev]

@mamund Sounds good.

[mamund]

thanks. i'm leaving this open but taking it off the first I-D milestone

[mamund]

@fosdev @fosrias (not sure which to use here ;)

do you want to take a run at writing up some guidance on this? maybe a para or two w/ and example? we can add a section at the bottom that covers this and (eventually) some other "best practice" type of stuff.

if you're for it, just assign this one to yourself and cut a branch for this issue.

[fosrias]

@mamund I actually think this is a significant design issue that if not already resolved needs to be.

[mamund]

sounds good, @fosrias

open up a thread on the list write up a strawman draft as a solution we can discuss, resolve, and adopt.

[fosdev]

@mamund Does the following expose the issue sufficiently IYO:

Here is a valid un-dereferenced ALPS document:

<alps>
  <descriptor id="fname" type="semantic"/>
  <descriptor id="contact" type="semantic">
    <descriptor href="fname"/>
  </descriptor>
  <descriptor id="person" type="semantic">
    <descriptor href="fname"/>
  </descriptor>
</alps>

If you dereference it, it becomes an invalid ALPS document:

<alps>
  <descriptor id="fname" type="semantic"/>
  <descriptor id="contact" type="semantic">
    <descriptor id="fname" type="semantic"/>
  </descriptor>
  <descriptor id="person" type="semantic">
    <descriptor id="fname" type="semantic"/>
  </descriptor>
</alps>

And this problem and potential for non-unique document-wide ids only gets worse when an href references an external ALPS profile.

[mamund]

this "de-referencing" example is a real surprise to me. It did not occur to me to replace references w/ inline content. I have been treating references in a doc the way you'd treat variables in code. 1) a declaration at the top, and 2) a use of that declared element in one or more places.

what you are showing me here looks, to me, to be some kind of duplication, not a reference.

so, before debating the value of this interpretation, which i agree results in an invalid document, i'd like to know your idea on how to get what you want without resulting in something invalid. what ideas do you have that provide a fix?

how is this handled in XML, JSON, and YAML today?

[fosdev]

So, here is another version that show the problem if dereferencing external docs:

Here is a valid un-dereferenced ALPS documents:

.../profile1
<alps>
  <descriptor id="fname" type="semantic"/>
  <descriptor id="person" type="semantic">
    <descriptor href="fname"/>
  </descriptor>
</alps>

.../profile2
<alps>
  <descriptor id="fname" type="semantic"/>
  <descriptor id="contact" type="semantic">
    <descriptor href="fname"/>
  </descriptor>
  <descriptor href=".../profile1#person/>
</alps>

If you dereference it, it becomes an invalid ALPS document:

.../profile2 - dereferenced
<alps>
  <descriptor id="fname" type="semantic"/>
  <descriptor id="contact" type="semantic">
    <descriptor id="fname" type="semantic"/>
  </descriptor>
  <descriptor id="person" type="semantic">
    <descriptor id="fname" type="semantic"/>
  </descriptor>
</alps>

Neither JSON or YAML support dereferencing/using other files per their spec. Usually some other spec would say how to do that (e.g. $ref in OpenAPI). They don't support multiple instances of keys at the same level, in JSON this is an error, in YAML it just uses the first value for the key. In xml, there is namespacing.

I think the in-line replacement of a reference is actually a reasonable approach and frankly I cannot imagine what a different one would be. I think the only way to solve this would be to use namespacing inside the id. That is straightforward with external references, but not so with internal. So, a possible convention would be the following:

<alps>
  <descriptor id="fname" type="semantic"/>
  <descriptor id="contact" type="semantic">
    <descriptor id="#1:fname" type="semantic"/>
  </descriptor>
  <descriptor id=".../profile1:person" type="semantic">
    <descriptor id=".../profile1:fname" type="semantic"/>
  </descriptor>
</alps>

The wonky one is if you re-use the internal fname multiple times as to what is the convention there. I am adding an arbitrary number and the # namespacing to local.

If then uses a convention to use the value after : in an id, if present whenever an id per ALPS convention has meaning. One could also have the convention that if no name was in the de-referenced descriptor the name could be populated with the id.

Those are some thoughts @mamund.