rspec/rules/S3838/xml/rule.adoc

== Why is this an issue?

Having robust documentation just makes life easier. That applies to XSD's as well. Each one should include a description of its intended use, and perhaps versioning.


This rule raises an issue when there's neither a comment before the ``++<xs:schema>++`` tag, nor ``++<xsd:annotation><xsd:documentation>...</xsd:documentation></xsd:annotation>++`` just inside the ``++<xs:schema>++`` element.


=== Noncompliant code example

[source,xml]
----
<xs:schema targetNamespace="http://www.codeSamples.com/fruit"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified" version="1">
  <xs:element name="fruit">
    ...
  </xs:element>
</xs:schema>
----


=== Compliant solution

[source,xml]
----
<-- This schema is intended... -->
<xs:schema targetNamespace="http://www.codeSamples.com/fruit"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified" version="1">
  <xs:element name="fruit">
    ...
  </xs:element>
</xs:schema>
----
or

[source,xml]
----
<xs:schema targetNamespace="http://www.codeSamples.com/fruit"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified" version="1">
  <xsd:annotation>
    <xsd:documentation>
      This schema is intended...
    </xsd:documentation:
  </xsd:annotation>
  <xs:element name="fruit">
    ...
  </xs:element>
</xs:schema>
----

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Add a description to document this schema.


=== Highlighting

``++<xs:schema>++``


endif::env-github,rspecator-view[]