Algorithm Terms and IRI expansion algorithm contradict each other

[daenney]

In section 1.4.1 Algorithm Terms (emphasis mine):

IRI expanding
Used as a macro within various algorithms as to reduce the language used to describe the process of expanding a string value representing an IRI or keyword using an active context either specified directly, or coming from the scope of the algorithm step using this term. Optional defined and local context arguments are used, if explicitly provided. Unless specified, the document relative flag defaults to false, and the vocab flag defaults to true.

• default relative: false
• default vocab: true

In section 5.2.2 IRI Expansion Algorithm (emphasis mine):

The algorithm takes two required and four optional input
variables. The required inputs are an active context and a
value to be expanded. The optional inputs are two flags,
document relative and vocab, that specifying whether value
can be interpreted as a relative IRI reference against the
document's base IRI or the active context's vocabulary
mapping, respectively, and a local context and a map
defined to be used when this algorithm is used during
Context Processing. If not passed, the two flags are set to
false and local context and defined are initialized to null.

• default relative: false
• default vocab: false

Step 13.4.4 of expansion, section 5.1.2, does not specify the value for vocab, so I went with false as per the default specified by the IRI expansion algorithm. This makes things not work. Seeing as step 13.4.3 explicitly specifies false for vocab it does seem like the default should be true and the IRI expansion algorithm introduction contains a mistake.

[gkellogg]

In section 1.4.1 Algorithm Terms (emphasis mine):

IRI expanding
Used as a macro within various algorithms as to reduce the language used to describe the process of expanding a string value representing an IRI or keyword using an active context either specified directly, or coming from the scope of the algorithm step using this term. Optional defined and local context arguments are used, if explicitly provided. Unless specified, the document relative flag defaults to false, and the vocab flag defaults to true.

• default relative: false
• default vocab: true

Yes, it's intentional that these values differ from the default for the algorithm, as that represented the general usage within the spec when the macro was introduced.

In section 5.2.2 IRI Expansion Algorithm (emphasis mine):

The algorithm takes two required and four optional input
variables. The required inputs are an active context and a
value to be expanded. The optional inputs are two flags,
document relative and vocab, that specifying whether value
can be interpreted as a relative IRI reference against the
document's base IRI or the active context's vocabulary
mapping, respectively, and a local context and a map
defined to be used when this algorithm is used during
Context Processing. If not passed, the two flags are set to
false and local context and defined are initialized to null.

• default relative: false
• default vocab: false

Again, correct.

Step 13.4.4 of expansion, section 5.1.2, does not specify the value for vocab, so I went with false as per the default specified by the IRI expansion algorithm. This makes things not work. Seeing as step 13.4.3 explicitly specifies false for vocab it does seem like the default should be true and the IRI expansion algorithm introduction contains a mistake.

I believe you're discussing 13.4.4.3:

Otherwise, if value is a default object, set expanded value to a new default object with the value of @default set to the result of IRI expanding value using type-scoped context for active context, and true for document relative.

So, the macro-default of true for vocab (and false for document relative) would be in effect. 13.4.3.2 does use true for document relative and false for vocab, so the algorithm would be invoked with true for both document relative and vocab, which was a specific design choice, as it is generally considered vocabulary-relative, but there are common cases where the type is defined within a document, so it can fall back to being document-relative.

The language in these steps invokes the IRI expanding macro (rather than invoking the algorithm directly), for which the default for vocab is true, which is probably what's tripping you up.

[daenney]

The language in these steps invokes the IRI expanding macro (rather than invoking the algorithm directly), for which the default for vocab is true, which is probably what's tripping you up.

Right, indeed it does. I've gone in and reviewed all my call sites for IRI Expansion because it turns out they all go through the macro wrapper.

It might be helpful to call out the difference explicitly in the introduction of the IRI expansion algorithm, as the fact that those two would be different didn't occur to me at all. If that's acceptable I'm happy to submit a PR with that change.

[gkellogg]

It's hard to accept PRs from non-WG members, except for very small changes. I'll mark this to be done as part of a planned future update to the spec.