Support XInclude

[RaySinnema]

From @ApiSecRay on March 27, 2015 12:8

• when generating documentation
• when validating

Copied from original issue: restful-api-description-language/radl-core#1

[jonathanrobie]

This is not a problem for the stylesheet, as long as you use an XSLT processor that supports XInclude. Java tools have it harder, especially those that write to RADL files. It is not a problem for validation either, as long as you are using XInclude together with validation.

[jonathanrobie]

The extraction tools work primarily on the resource model. Having the resource model in a separate file might not be terribly difficult.

[RaySinnema]

The question is what we're trying to achieve by splitting things up.

If we're thinking about a service mashup scenario, then splitting along technical layers isn't terribly helpful; you'd want to split along functional layers instead.

We should identify use cases first.

[jonathanrobie]

The main use cases I see are:

1. Refreshing the resource model without disrupting the rest of the service description.
2. Keeping the size of individual files small to make them a little easier to edit.
3. Allowing different programmers to work on different files at the same time without clashing.

This came up because William requested it when doing Documentum Core REST in RADL.

[RaySinnema]

The first item is not an issue. The resource model is in a separate section of RADL, so the tools have no problem distinguishing it from the rest.

The interesting case is 3, I think. The question is what each of these different programmers are working on. Is one working on link relations and the other on the state diagram? Or is one working on both for feature X and the other also on both, but for feature Y?

[jonathanrobie]

This came up precisely because the Documentum team decided to split up files along the lines of 2.

XML has a mechanism for doing this. I don't think it's that hard to support it. It could be useful for people who want to generate RADL or have particular ways of editing in teams. I'm not sure how important this issue is.

[RaySinnema]

I understand the history of the issue. I was trying to think broader. We do have the service mashup use case as well, so whatever we come up with should be able to handle that as well.

[gentlewind]

It's NOT the case that developer A works on the relation, while developer B works on the state diagrams. Usually a developer writes the complete RADL for each particular resource from top to down, but at different phases he/she may still work on different parts (model, links, etc.).

The major problem is even for a REST Services that is not large (e.g. 40+ resources), there is already a huage RADL file created (e.g. 8000+ lines). In development mode, it makes sense to split the entire RADL into multiple files. It has benefits for engineering productivity.

[jonathanrobie]

Another use I am seeing: generating examples in separate files, and using XInclude to include them into the RADL description.

[jonathanrobie]

I removed the schema level because this has nothing to do with the schema.

The stylesheets work with XInclude as long as your XSLT processor is invoked with the XInclude option. Validation with Jing requires preprocessing with an XInclude processor such as the XSLT processor. There is no technical issue for either validation or transformation.

Can we close this issue?

[gentlewind]

I checked that when xinclude is used, the generated HTML file is a skeleton file. This issue shall be fixed in the RADL tool radl2docs. I can work on the fix but I think this issue is with lower priority.

[jonathanrobie]

Until the Java tools support it, people can use XInclude in their source and expand it before calling the Java tools. Alternatively, they can call XSLT directly with the XInclude option.

This should be fixed in the Java tools, I agree that this is not essential to fix in the RESTFest milestone. There are good workarounds.

[jonathanrobie]

Is this done? Should I close this issue?