petrochenko-pavel-a / raml-js-parser2-issues

0 stars 0 forks source link

#References to inner elements of external files: clarifications needed #56

Closed VasiliyLysokobylko closed 8 years ago

VasiliyLysokobylko commented 8 years ago

If would suggest some improvements regarding XSD-type references.

Dereferencing to a fragment of XSD schema is defined at http://www.w3.org/TR/xmlschema-1/

Most people would have a hard time figuring out where this is in the spec. I suggest changing it to:

Dereferencing to a fragment of XSD schema is described in 3.15.2.2 References to Schema Components, XML Schema Part 1: Structures Second Edition

Change:

If you are referring to unique named complex type within XSD schema you...

To:

If you are referring to a named type within XSD schema you...

In a valid schema, qualified names of types are unique. Your syntactic sugar proposal implicitly limits this to the types defined in the file (as opposed to the entire schema set brought in scope by referencing the particular file), therefore the local names of the types in the file are implicitly unique.

Furthermore there is no reason to limit the above to complex types. All types (simple and complex) share the same symbol space. This allows one to reference simple types as well.

Which brings another interesting point: what if someone wants to directly use XSD's type system, e.g. xsd:unsignedShort? Could we explicitly direct these scenarios using http://www.w3.org/2001/XMLSchema.xsd#unsignedShort or http://www.w3.org/2009/XMLSchema/XMLSchema.xsd#unsignedShort? the problem here being these URLs cannot be dereferenced like any other user defined schemas/simple and/or complex types.

Lastly, the spec could recommend the XPointer Framework instead of the schema spec reference, specifically the use of the shorthand notation (to avoid any confusion around namespaces, maybe indicate it is the only recommended one?):

xpointer(schema/element[@name="person"])

The shorthand notation fits perfectly here:

A shorthand pointer, formerly known as a barename, consists of an NCName alone. It identifies at most one element in the resource's information set; specifically, the first one (if any) in document order that has a matching NCName as an identifier.

VasiliyLysokobylko commented 8 years ago

https://github.com/raml-org/raml-spec/issues/203