ext not re-usable in profile.

[fosdev]

Currently, the ext tag needs an href or something to allow it to be re-usable. Further, I think it needs to support a more abstract meaning potentially than something as concrete as the example here: https://github.com/alps-io/spec/blob/master/draft-00/draft-00.txt#L978

It may already do that, but I think an example would be good, where one may want to indicate some metadata about a list of options, vs. the actual options which may change at runtime.

Also, seems like some more instructions as to what should be an an extension document as an example. If it is just human readable name, why the need for the human readable tag in extension itself.

[mamund]

@fosdev:

first, ext does include an href ATM, in fact, it's a MUST. did you mean something else here?

as for abstract-ness. i'd like to see some examples. FWIW, in my head, it seems that what appears within <ext> and </ext> could be up for grabs. maybe like an Atom extension that has some identifier so that consumers can recognize what is about to appear inside:

<ext href="http://example.com/alps-extensions/boat" id="myboat">
  <boat id="123">
    <name>Sea Son</name>
    <type>Cigarette</type>
    <model>50 ft Marauder SS</model>
  </boat>
</ext>

[mamund]

@fosdev:

"Also, seems like some more instructions as to what should be an an extension document as an example. If it is just human readable name, why the need for the human readable tag in extension itself."

IIUYC, the point is that any reasonably complex extension is likely to need some documentation and that is where it goes. IMO, if the extension is incredibly simple, the href might point to a document which is actually a list of ALPS extensions and reads mostly as a dictionary or glossary of terms.

Open to other ideas and willing incorporate this into the docs.

[fosdev]

Ok. I think I see where the re-usability issue lies. If I define an extension and I set its value in a specific profile, how can I reuse that ext definition and its value in the same profile because if it is not a relative fragment, and thus it implies an external reference. That is on what basis would I look inside the current profile to find the definition of that extension value. Make sense? Contrived example:

<alps>
  <ext href="http://example.com/alps-extensions/boat" id="myboat">
    <boat id="123">
      <name>Sea Son</name>
      <type>Cigarette</type>
      <model>50 ft Marauder SS</model>
    </boat>
    </ext>
  <descriptor id="dryDock">
    <ext href="http://example.com/alps-extensions/boat"/>
  </descriptor>
   <descriptor id="trailer">
    <ext href="http://example.com/alps-extensions/boat"/>
  </descriptor>
</alps>

Does that clarify? How do I stay DRY for an extension. I also ponder how could one reuse that extension across different profiles with it's defined value. Your example includes and id attribute that could allow that, but there is not id property on the ext per the spec ATM.

Further, the following references a 'name' property that is confusing because you say there are only 2 properties href and value:

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

So, I think that wording needs to be cleaned up as well.

[mamund]

@fosdev

The last item you mention here (mentioning the href and name elements of ext) relate only to possible registration of the extension for others to use.

[mamund]

@fosdev:

If I define an extension and I set its value in a specific profile, how can I reuse that ext definition and its value in the same profile because if it is not a relative fragment, and thus it implies an external reference.

OK, as this is starting to get out of hand, I think this is more than a clarification issue. Originally, I added ext as a simple name/value pair pattern for things like content quality (enumerations) or single-value properties that were not included in the spec (<ext name="page-size" value="50" />). However, in this thread I just expanded ext WAY beyond that. And that may be a big problem!

IIRC, @leonardr was not a fan of this element (possibly for this very reason), too. Now, even though I like it, maybe it needs to go away?

[fosdev]

I think ext is valuable. Should be reusable and possibly reference another descriptor to define its value.

[mamund]

took another stab at clearing up the definition here. this includes adding id as REQUIRED so that you can be DRY and use a single <ext>element in several places. Note i still have <ext> as a child of <descriptor> and <alps>.

check it out here and post any comments before i close this out: 7a20fde

[fosdev]

@mamund This is better, but I am not sure it addresses the reusability aspect of an extension within a document. How does having a required id allow re-usablility.

That is, since href points to an external definition document you can't do something like:

<ext id="something">
<descriptor id="something_else">
  <ext href="#something"/>
</descriptor>

and you could not reference an extension in an external profile either. Sort of a bit of a pickle on this one. How do you see re-using this in a doc? Also, now that I am thinking about it, you only define fragments in the context of descriptors, so there is no clear convention for referencing an external ext element.

Sort of makes me wonder if the best way to do this would be to have a descriptor type=ext and do this in the context of extending a descriptor with related properties. Anyhow, am I missing something?

[fosdev]

Actually, if you use href in standard fashion as a descriptor for internal and external reference and use a 'doc' section in the extension with an href to the definition, I think you can solve it. That is in a ext you MUST have a doc with an href to an external definition. Sorry, for the meandering.

[fosdev]

@mamund And yet deeper in I see this:

https://github.com/alps-io/spec/blob/master/draft-00.txt#L1029-L1035
https://github.com/alps-io/spec/blob/master/draft-00.txt#L1021

which basically shows how to extend a descriptor and re-use it. So, this is probably the answer, but I think it warrants highlighting this as the approach to re-use. Not sure the average man will savy this. Should this be here, or in the best practices document I am 'supposed' to be working on?

However, this would not address re-usability on the ALPS level vs descriptor level.

[fosdev]

@mamund and one more thing, do you think value should be an attribute of extension only or a tag or could I embed some object in the extension tag itself (seems one might want to do something that involves more than what you would want to define in an attribute). If I can embed some value or object in the tag, does that need some clarification?

[fosdev]

And at the extent of beating this horse well beyond death and recognition, the nice thing about my proposed constraint about doc/href for the docmentation and freeing up href is the idea that you can extend extensions, which reminds me of our dynamic extension discussion as we were walking around the piers searching for a restaurant if my memory serves me correctly.

[fosrias]

@mamund I think I have a work around for simple re-usability that could close out this issue. That is, the href can point to another element either relatively in the same document or in another ALPS document just like a descriptor. The caveat is that you can only href an tag that has an href to human readable documents.

You could ease this so you could extend other elements if somewhere it resolves to human readable documents.

Other approach is to decouple href from human readable meaning and use a element with a help rel or something. In any case, wanted to throw this idea in the mix.

[mamund]

i've read this through a couple times and can't come up w/ how this
looks/works. can you toss in an example here?

​

[fosrias]

@mamund Couple of thoughts.

1. I should be able to describe an extension in ALPS document once (stay DRY) and re-use in in multiple places in that same document. This is tantamount to defining a top-level descriptor and then re-using it throughout the document as a nested descriptor, for example.

An example is if I am using an extension to say that a descriptor is a list data type or an enum, I may want to decorate more than one descriptor that way in a document.

2. If can re-use an ext element defined in an ALPS document, I SHOULD be able to reference an ext element defined in another ALPS document (maybe an extension only ALPS document).

The issue here is this, re-use, that is referencing is accomplished by href to the id of another element generally in ALPS. This works fine for a descriptor, but not ext because href is reserved for documentation of the extension.

What is being extended, an alps element or a description element and as such I think it should reflect how those are documented, i.e. use a doc element and reserve href for referencing.

I think the right way to solve all this is something like this:

The 'ext' element has the following properties.

1.  'id'

2.  'href'

3.  'value'

4.   'doc'

The 'id' property is REQUIRED.  The 'href' is OPTIONAL.  
The 'value' property is OPTIONAL.  The 'doc' is RECOMMENDED
since the content is undetermined; its meaning and use SHOULD 
be explained by the `doc`.

If present, the 'href' property MUST be a dereferenceable URL, that
points to another 'ext' either within the current ALPS
document or in another ALPS document.

This would be a breaking change in the current spec, but I think it is the correct way to do this.

[mamund]

Sounds reasonable. Write up some examples to show how it works and we can discuss.

[fosrias]

Couple possibilities:

<alps>
  <ext id="reusable-enum-def" value="on off" />
  <descriptor id="switch" type="semantic">
    <ext href="#reusable-enum-def/>
  </descriptor>
  <descriptor id="light-bulb" type="semantic">
    <ext href="#reusable-enum-def"/>
  </descriptor>
</alps>

or support ext as xml property

<alps>
  <ext id="reusable-enum-def" value="on off" />
  <descriptor id="switch" type="semantic" ext="#reusable-enum-def"/>
  <descriptor id="light-bulb" type="semantic" ext="#reusable-enum-def"/>
</alps>

[fosrias]

@mamund These examples clarify?

[mamund]

not yet.

first one make sense but second one (as attribute) doesn't yet. i'm wary of using EXT references as they are not returning the same thing as other refs (DOC and LINK). we may be running into challenges on what to expect in reply

there's a REL on LINK, there's an implied expectation on DOC and now w/ EXT as a possible href there are additional challenges.

we should proly discuss this one live sometime to sort things out, eh?

[fosrias]

Yes. We are not consistent on uses of the same thing @mamund across different components