Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Would you include an XML schema for a new file format in a software specification document or would you consider this too specific? Or would it be already too specific to require XML at this point?

share|improve this question

5 Answers 5

up vote 1 down vote accepted

If the schema already exists, then I don't see why you wouldn't want to specify that your system must use a particular schema (and version of that schema) for data storage or transfer. This sounds like a non-functional requirement to me, specifically what Karl Wiegers refers to as either a Software Interface Requirement or a Communications Interface Requirement.

However, if the schema is to be constructed, then the requirement itself should not even specify that XML is used to store and transfer data, but the constraints should be documented elsewhere in the requirements document(s). In this case, the requirement should be written to inform the developers of what must be accomplished, giving them as much room to make design decisions as possible. Again, the SRS template provided by Karl Wiegers has sections titled Operating Environment and Design and Implementation Constraints where you can specify various considerations that developers must be aware of when making the system.

share|improve this answer

If the XML Schema constrains data/documents on the boundary of your system then they can be referenced by the document that defines the system interfaces. Some projects refer to this as the Interface Control Document (ICD).

The ICD distinguishes between supplied and provided interfaces and acts as a kind of contract between your system and one or more other systems.

share|improve this answer

XML schema is part of the design because the way schema is designed affects the algorithms of reading, writing and searching which have impact on performance.

  • If by specification you mean Requirement specification then the answer is No it should not be there. Requirements specifications should not refer to file formats unless they are constraints from the environment like when they are needed for data interchange with another system in this case it should be included.
  • If you mean Design specification then Yes it must be included. However if the system is complex or large and design is split into "High Level" (Architecture) and "Detailed Level" then it should be included in the Detailed Level Design only. High Level design should only mention that XML technology should be used for storage.

If the system is simple and the schema design will have no great impact on performance or in case the schema is straight forward generated by a software component you may just skip it.

share|improve this answer

Well like anything else, "it depends". If the interface is essential to your product/project and the details of the specification will influence a lot of work that needs to be done within or outside your team then absolutely I'd specify it up front.

share|improve this answer

If it's a high-level specification which just says "System X will do task Y with file Z", then yes, it's too specific. If it's a detailed spec that says "System X will implement a web service to perform task Y using XML file Z that is sent from client system A", then yes, you should include the schema. It does not have to be in the main document, but make sure it's in an appendix somewhere so readers can get the right idea.

share|improve this answer
    
+1: especially if the XML defines an interface to a legacy system. –  Peter K. Jul 6 '11 at 14:11

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.