Question

I have a RESTful API supporting CRUD operations on an entity. Should I have single xsd file that defines the schema for all the CRUD operations?

The reason why I ask this question is, I have some fields that are relevant only for Retrieve calls and not for Create or Update. In that case, should I have one xsd file and ignore some fields for Create and Update?

Answer 1

Your question seems to tie together fields usage with number of XSD files, which makes me think you may be missing on some basic XSD concepts.

Let’s say that your problem is that for a given entity, you may retrieve more fields than you can update; illustrating on a fictitious Person entity, you may R(etrieve) the Name, Address, Date of Birth and Registered Since attributes, yet to C(reate) the entity, you only allow for Name, Address and Date of Birth – you want the backend system to set the Registered Since attribute. The requirement is to constrain the XSD as much as possible, to improve the self-descriptiveness of the model.

You can achieve the separation of these scenarios by creating an XSD base type, then extend that using another type, which will then include the extra fields you want. You could do this kind of stuff in a single file, or two or more different files.

<?xml version="1.0" encoding="utf-8" ?>
<!--XML Schema generated by QTAssistant/XML Schema Refactoring (XSR) Module (http://www.paschidev.com)-->
<xsd:schema targetNamespace="http://tempuri.org/XMLSchema.xsd" elementFormDefault="qualified" xmlns="http://tempuri.org/XMLSchema.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <xsd:complexType name="PersonBase">
        <xsd:sequence>
            <xsd:element name="Name"/>
            <xsd:element name="Address"/>
            <xsd:element name="DateOfBirth"/>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="PersonToRetrieve">
        <xsd:complexContent>
            <xsd:extension base="PersonBase">
                <xsd:sequence>
                    <xsd:element name="RegisteredSince"/>
                </xsd:sequence>
            </xsd:extension>
        </xsd:complexContent>
    </xsd:complexType>
</xsd:schema>

NOTE: The XSD above is not intented to illustrate XSD best practices

If extension/restriction is not allowed in your environment, you could achieve reuse by virtue of xsd:group – it doesn’t change my point. So, I am basically saying that the reason why you’re asking the question – I have some fields that are relevant only for Retrieve calls and not for Create or Update. – has no bearing whatsoever on the number of XSD files… unless you consider more variables. I’ll try some that come to my mind, but I am not going to provide an exhaustive list:

• Complexity: If the problem you’re trying to solve is simple, then try to keep the solution simple. As shown above, you can still solve your “descriptiveness” problem using one XSD file. If you consider tools as part of the problem space, many tools have issues with complex relationships between XSDs… sometimes xsd:include is not even supported, and command lines become more complicated.
• XML Namespaces: If you’re like me or many others that would rather keep a separation between the constructs that describe your business domain vs. supporting your API definition and messaging, then using different XML namespaces is a common solution. You need at least as many different XSD files as XML namespaces you decide to go with. This would drive you to have more than one XSD files.
• Reusable Content: XSD content can be reused in many ways. If you have a basic type system you want to see enforced across many projects/interfaces, then a good practice is to author them in one or more separate XSD files, then include/import them by other, more specific XSDs.
• XML Schema Refactoring: If you’re in an environment where people use automatic refactoring, the answer will be: who cares? I know first hand that neophytes find this answer pretentious; yet, in real life with complex systems, some solutions to your question are actually so hard to deal with, because of personal preferences (code/model reviews, etc.), and/or variety of tools/platforms with different level of support, XSD to code included, that XSD refactoring is most likely the only way to keep things running smoothly.