Identifiers and References

Syntax-only versus must-resolve

The validator keys off a field's declared ValueType, never its name: a TypeIdentifier field checks syntax only, while a TypeReference field must resolve in the TypeRegistry or the compiler reports an error.

TypeIdentifier and TypeReference

type:TypeIdentifier names the FQN a Block definition is minting — the named type need not already exist, because the definition is what creates it.

type:TypeReference names a type that must already exist — used for baseType, member types, and other sites where the compiler needs a real target to resolve against.

An unresolved reference is not a broken document

An unresolved TypeReference is an error, but not proof the document is ill-formed — like a Java class-not-found, it may simply be a typo or a library that is not yet on the classpath.

Minting a type, then referencing it

Defining a Block mints its FQN through a TypeIdentifier field; a second Block extending it uses that same FQN through a TypeReference field, which must now resolve.

<!-- Widget mints its own FQN through the "type" TypeIdentifier field -->
<block>
  <type>com.acme.example.Widget</type>
  <baseType>org.blockml.bml.core.Block</baseType>
</block>

<!-- Gadget references Widget's FQN through the "baseType" TypeReference field -->
<block>
  <type>com.acme.example.Gadget</type>
  <baseType>com.acme.example.Widget</baseType>
</block>

Widget's type field is checked only for well-formed syntax, since it is minting a brand-new FQN; Gadget's baseType field is checked for existence, since com.acme.example.Widget must already resolve in the TypeRegistry for Gadget to be valid. The same FQN text plays two different validator roles depending on which field carries it.

What to carry into the next pages

After this page, readers should be able to predict whether an unresolved name is a syntax error or a validator error, closing out the Foundations group before the type system pages begin.

Continue with the type system