Validation documentation

examples/pom.xml

@@ -30,6 +30,11 @@
 			<artifactId>hapi-fhir-structures-hl7org-dstu2</artifactId>
 			<version>1.2-SNAPSHOT</version>
 		</dependency>
+		<dependency>
+			<groupId>ca.uhn.hapi.fhir</groupId>
+			<artifactId>hapi-fhir-validation-resources-dstu2</artifactId>
+			<version>1.2-SNAPSHOT</version>
+		</dependency>
 		<dependency>
 			<groupId>javax.servlet</groupId>
 			<artifactId>javax.servlet-api</artifactId>

examples/src/main/java/example/ValidatorExamples.java

@@ -8,17 +8,22 @@ import javax.servlet.ServletException;
 
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.io.filefilter.WildcardFileFilter;
+import org.hl7.fhir.instance.model.ValueSet;
 import org.hl7.fhir.instance.model.api.IBaseResource;
 
 import ca.uhn.fhir.context.FhirContext;
+import ca.uhn.fhir.model.dstu2.resource.Observation;
 import ca.uhn.fhir.model.dstu2.resource.OperationOutcome;
 import ca.uhn.fhir.model.dstu2.resource.Patient;
 import ca.uhn.fhir.model.dstu2.valueset.ContactPointSystemEnum;
+import ca.uhn.fhir.model.primitive.StringDt;
 import ca.uhn.fhir.parser.IParser;
 import ca.uhn.fhir.parser.StrictErrorHandler;
 import ca.uhn.fhir.rest.client.IGenericClient;
 import ca.uhn.fhir.rest.server.RestfulServer;
+import ca.uhn.fhir.validation.FhirInstanceValidator;
 import ca.uhn.fhir.validation.FhirValidator;
+import ca.uhn.fhir.validation.IValidationSupport;
 import ca.uhn.fhir.validation.SingleValidationMessage;
 import ca.uhn.fhir.validation.ValidationResult;
 
@@ -114,10 +119,88 @@ public class ValidatorExamples {
    }
 
    public static void main(String[] args) throws Exception {
-      validateFiles();
+      instanceValidator();
 
    }
 
+   private static void instanceValidator() throws Exception {
+      // START SNIPPET: instanceValidator
+      FhirContext ctx = FhirContext.forDstu2();
+
+      // Create a FhirInstanceValidator and register it to a validator
+      FhirValidator validator = ctx.newValidator();
+      FhirInstanceValidator instanceValidator = new FhirInstanceValidator();
+      validator.registerValidatorModule(instanceValidator);
+      
+      /*
+       * Let's create a resource to validate. This Observation has some fields
+       * populated, but it is missing Observation.status, which is mandatory.
+       */
+      Observation obs = new Observation();
+      obs.getCode().addCoding().setSystem("http://loinc.org").setCode("12345-6");
+      obs.setValue(new StringDt("This is a value"));
+      
+      // Validate
+      ValidationResult result = validator.validateWithResult(obs);
+      
+      // Do we have any errors or fatal errors?
+      System.out.println(result.isSuccessful()); // false
+      
+      // Show the issues
+      for (SingleValidationMessage next : result.getMessages()) {
+         System.out.println(" Next issue " + next.getSeverity() + " - " + next.getLocationString() + " - " + next.getMessage());
+      }
+      // Prints:
+      // Next issue ERROR - /f:Observation - Element '/f:Observation.status': minimum required = 1, but only found 0
+      // Next issue WARNING - /f:Observation/f:code - Unable to validate code "12345-6" in code system "http://loinc.org"
+      
+      // You can also convert the result into an operation outcome if you 
+      // need to return one from a server
+      OperationOutcome oo = (OperationOutcome) result.toOperationOutcome();
+      // END SNIPPET: instanceValidator
+   }
+   
+   private static void instanceValidatorCustom() throws Exception {
+      // START SNIPPET: instanceValidatorCustom
+      FhirContext ctx = FhirContext.forDstu2();
+
+      // Create a FhirInstanceValidator and register it to a validator
+      FhirValidator validator = ctx.newValidator();
+      FhirInstanceValidator instanceValidator = new FhirInstanceValidator();
+      validator.registerValidatorModule(instanceValidator);
+      
+      IValidationSupport valSupport = new IValidationSupport() {
+         
+         @Override
+         public org.hl7.fhir.instance.utils.IWorkerContext.ValidationResult validateCode(String theCodeSystem, String theCode, String theDisplay) {
+            // TODO: Implement
+            return null;
+         }
+         
+         @Override
+         public boolean isCodeSystemSupported(String theSystem) {
+            // TODO: Implement
+            return false;
+         }
+         
+         @Override
+         public <T extends IBaseResource> T fetchResource(FhirContext theContext, Class<T> theClass, String theUri) {
+            // TODO: Implement
+            return null;
+         }
+         
+         @Override
+         public ValueSet fetchCodeSystem(String theSystem) {
+            // TODO: Implement
+            return null;
+         }
+      };
+      instanceValidator.setValidationSupport(valSupport);
+   
+      // END SNIPPET: instanceValidatorCustom
+   }
+   
+   @SuppressWarnings("unused")
    private static void validateFiles() throws Exception {
       // START SNIPPET: validateFiles
       FhirContext ctx = FhirContext.forDstu2();

hapi-fhir-base/src/main/java/ca/uhn/fhir/validation/FhirValidator.java

@@ -54,14 +54,13 @@ public class FhirValidator {
 
 	private static volatile Boolean ourPhlocPresentOnClasspath;
 	private final FhirContext myContext;
-	private volatile List<IValidatorModule> myValidators = new ArrayList<IValidatorModule>();
+	private List<IValidatorModule> myValidators = new ArrayList<IValidatorModule>();
 
 	/**
 	 * Constructor (this should not be called directly, but rather {@link FhirContext#newValidator()} should be called to obtain an instance of {@link FhirValidator})
 	 */
 	public FhirValidator(FhirContext theFhirContext) {
 		myContext = theFhirContext;
-		setValidateAgainstStandardSchema(true);
 
 		if (ourPhlocPresentOnClasspath == null) {
 			try {
@@ -72,10 +71,6 @@ public class FhirValidator {
 				ourPhlocPresentOnClasspath = false;
 			}
 		}
-		if (ourPhlocPresentOnClasspath) {
-			setValidateAgainstStandardSchematron(true);
-		}
-
 	}
 
 	private void addOrRemoveValidator(boolean theValidateAgainstStandardSchema, Class<? extends IValidatorModule> type, IValidatorModule theInstance) {
@@ -183,7 +178,9 @@ public class FhirValidator {
 	@Deprecated
 	public void validate(Bundle theBundle) {
 		Validate.notNull(theBundle, "theBundle must not be null");
-
+		
+		applyDefaultValidators();
+		
 		IValidationContext<Bundle> ctx = ValidationContext.forBundle(myContext, theBundle);
 
 		for (IValidatorModule next : myValidators) {
@@ -197,6 +194,15 @@ public class FhirValidator {
 
 	}
 
+	private void applyDefaultValidators() {
+		if (myValidators.isEmpty()) {
+			setValidateAgainstStandardSchema(true);
+			if (ourPhlocPresentOnClasspath) {
+				setValidateAgainstStandardSchematron(true);
+			}
+		}
+	}
+
 	/**
 	 * Validates a resource instance, throwing a {@link ValidationFailureException} if the validation fails
 	 * 
@@ -208,6 +214,9 @@ public class FhirValidator {
 	 */
 	@Deprecated
 	public void validate(IResource theResource) throws ValidationFailureException {
+		
+		applyDefaultValidators();
+		
 		ValidationResult validationResult = validateWithResult(theResource);
 		if (!validationResult.isSuccessful()) {
 			throw new ValidationFailureException(myContext, validationResult.toOperationOutcome());
@@ -224,7 +233,9 @@ public class FhirValidator {
 	 */
 	public ValidationResult validateWithResult(Bundle theBundle) {
 		Validate.notNull(theBundle, "theBundle must not be null");
-
+		
+		applyDefaultValidators();
+		
 		IValidationContext<Bundle> ctx = ValidationContext.forBundle(myContext, theBundle);
 
 		for (IValidatorModule next : myValidators) {
@@ -244,7 +255,9 @@ public class FhirValidator {
 	 */
 	public ValidationResult validateWithResult(IBaseResource theResource) {
 		Validate.notNull(theResource, "theResource must not be null");
-
+		
+		applyDefaultValidators();
+		
 		IValidationContext<IBaseResource> ctx = ValidationContext.forResource(myContext, theResource);
 
 		for (IValidatorModule next : myValidators) {
@@ -264,7 +277,9 @@ public class FhirValidator {
 	 */
 	public ValidationResult validateWithResult(String theResource) {
 		Validate.notNull(theResource, "theResource must not be null");
-
+		
+		applyDefaultValidators();
+		
 		IValidationContext<IBaseResource> ctx = ValidationContext.forText(myContext, theResource);
 
 		for (IValidatorModule next : myValidators) {

hapi-fhir-base/src/main/java/ca/uhn/fhir/validation/ValidationResult.java

@@ -59,7 +59,10 @@ public class ValidationResult {
 	}
 
 	/**
-	 * Was the validation successful
+	 * Was the validation successful (in other words, do we have no issues that are at
+	 * severity {@link ResultSeverityEnum#ERROR} or {@link ResultSeverityEnum#FATAL}. A validation
+	 * is still considered successful if it only has issues at level {@link ResultSeverityEnum#WARNING} or
+	 * lower. 
 	 * 
 	 * @return true if the validation was successful
 	 */

hapi-fhir-structures-hl7org-dstu2/src/main/java/ca/uhn/fhir/validation/FhirInstanceValidator.java

@@ -93,10 +93,17 @@ public class FhirInstanceValidator extends BaseValidatorBridge implements IValid
 
   /**
    * Returns the "best practice" warning level (default is
-   * {@link BestPracticeWarningLevel#Hint})
+   * {@link BestPracticeWarningLevel#Hint}). 
+   * <p>
+   * The FHIR Instance Validator has
+   * a number of checks for best practices in terms of FHIR usage. If this setting
+   * is set to {@link BestPracticeWarningLevel#Error}, any resource data which does not
+   * meet these best practices will be reported at the ERROR level. If this setting
+   * is set to {@link BestPracticeWarningLevel#Ignore}, best practice guielines will
+   * be ignored.
+   * </p> 
    * 
-   * @see #setBestPracticeWarningLevel(BestPracticeWarningLevel) for more
+   * @see {@link #setBestPracticeWarningLevel(BestPracticeWarningLevel)}
-   *      information on this value
    */
   public BestPracticeWarningLevel getBestPracticeWarningLevel() {
     return myBestPracticeWarningLevel;
@@ -115,10 +122,14 @@ public class FhirInstanceValidator extends BaseValidatorBridge implements IValid
   /**
    * Sets the "best practice warning level". When validating, any deviations
    * from best practices will be reported at this level.
-   * {@link BestPracticeWarningLevel#Ignore} means that best practice deviations
+   * <p>
-   * will not be reported, {@link BestPracticeWarningLevel#Warning} means that
+   * The FHIR Instance Validator has
-   * best practice deviations will be reported as warnings, etc. Default is
+   * a number of checks for best practices in terms of FHIR usage. If this setting
-   * {@link BestPracticeWarningLevel#Hint}
+   * is set to {@link BestPracticeWarningLevel#Error}, any resource data which does not
+   * meet these best practices will be reported at the ERROR level. If this setting
+   * is set to {@link BestPracticeWarningLevel#Ignore}, best practice guielines will
+   * be ignored.
+   * </p> 
    * 
    * @param theBestPracticeWarningLevel
    *          The level, must not be <code>null</code>

src/site/resources/svg/hapi_usage_patterns.svg

@@ -163,7 +163,7 @@
 					Use the HAPI FHIR client in an application to fetch from or store
 					resources to an external server.
 					<br />
-					<a href="./doc_rest_client.html">Learn Mode</a>
+					<a href="/hapi-fhir/doc_rest_client.html">Learn Mode</a>
 				</div></div></foreignObject>
 				<text x="73" y="45" fill="#4D4D4D" text-anchor="middle"
 					font-size="12px" font-family="Helvetica">[Not supported by viewer]</text>
@@ -266,7 +266,7 @@
 					Use the HAPI FHIR server in an application to allow external
 					applications to access or modify your application's data.
 					<br />
-					<a href="./doc_rest_server.html">Learn More</a>
+					<a href="/hapi-fhir/doc_rest_server.html">Learn More</a>
 					<br />
 				</div></div></foreignObject>
 				<text x="73" y="53" fill="#4D4D4D" text-anchor="middle"
@@ -382,7 +382,7 @@
 					Use the HAPI JPA/Database Server to deploy a fully functional FHIR
 					server you can develop applications against.
 					<br />
-					<a href="./doc_jpa.html">Learn More</a>
+					<a href="/hapi-fhir/doc_jpa.html">Learn More</a>
 				</div></div></foreignObject>
 				<text x="73" y="59" fill="#4D4D4D" text-anchor="middle"
 					font-size="12px" font-family="Helvetica">[Not supported by viewer]</text>
@@ -572,7 +572,7 @@
 					Use the HAPI FHIR parser and encoder to convert between FHIR and
 					your application's data model.
 					<br />
-					<a href="./doc_fhirobjects.html">Learn More</a>
+					<a href="/hapi-fhir/doc_fhirobjects.html">Learn More</a>
 				</div></div></foreignObject>
 				<text x="73" y="45" fill="#4D4D4D" text-anchor="middle"
 					font-size="12px" font-family="Helvetica">[Not supported by viewer]</text>
@@ -591,4 +591,4 @@
 		<path d="M 565 399 C 565 407 595 407 595 399" fill="none" stroke="#666666"
 			stroke-miterlimit="10" pointer-events="none" />
 	</g>
-</svg>
+</svg>

src/site/site.xml

@@ -120,6 +120,8 @@
 			<item name="Core API" href="./apidocs/index.html" />
 			<item name="Model API (DSTU1)" href="./apidocs-dstu/index.html" />
 			<item name="Model API (DSTU2)" href="./apidocs-dstu2/index.html" />
+			<item name="Model API (RI DSTU2)" href="./apidocs-hl7org-dstu2/index.html" />
+			<item name="JPA Server API" href="./apidocs-jpaserver/index.html" />
 		</menu>
 		<menu name="JXR" inherit="top">
 			<item name="Core" href="./xref-base/index.html" />

src/site/xdoc/doc_validation.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
-	xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
 
 	<properties>
 		<title>Validation</title>
@@ -9,70 +8,82 @@
 
 	<body>
 		<section name="Validation">
-		
+
 			<p>
 				HAPI supportes two types of validation, both of which are described in the
 				sections below.
 			</p>
 			<ul>
 				<li>
-					<b>Parser Validation</b> is validation at runtime during the parsing
+					<b>Parser Validation</b>
+					is validation at runtime during the parsing
 					of a resource. It can be used to catch input data that is impossible to
-					fit into the HAPI data model. For example, it can be used to throw exceptions 
+					fit into the HAPI data model. For
+					example, it can be used to throw exceptions
 					or display error messages if a resource being parsed contains tags for which
 					there are no appropriate fields in a HAPI data structure.
 				</li>
 				<li>
-					<b>Resource Validation</b> is validation of the parsed (or constructed) resource against 
+					<b>Resource Validation</b>
+					is validation of the parsed (or constructed) resource against
 					the official FHIR validation rules (e.g. Schema/Schematron).
 				</li>
 			</ul>
-		
+
 		</section>
 
 		<section name="Parser Validation">
-			
+
 			<p>
-				Parser validation is controlled by calling <code>setParserErrorHandler(IParserErrorHandler)</code> on
+				Parser validation is controlled by calling
+				<code>setParserErrorHandler(IParserErrorHandler)</code>
+				on
 				either the FhirContext or on individual parser instances. This method
-				takes an <code>IParserErrorHandler</code>, which is a callback that
+				takes an
+				<code>IParserErrorHandler</code>
+				, which is a callback that
 				will be invoked any time a parse issue is detected.
-			</p>			
+			</p>
 			<p>
-				There are two implementations of <code>IParserErrorHandler</code> worth 
+				There are two implementations of
+				<code>IParserErrorHandler</code>
+				worth
 				mentioning. You can also supply your own implementation if you want.
 			</p>
 			<ul>
 				<li>
 					<a href="./apidocs/ca/uhn/fhir/parser/LenientErrorHandler.html">LenientErrorHandler</a>
 					logs any errors but does not abort parsing. By default this handler is used, and it
-					logs errors at "warning" level. It can also be configured to silently ignore issues.
+					logs errors at "warning" level. It can also be configured to silently
+					ignore issues.
 				</li>
 				<li>
 					<a href="./apidocs/ca/uhn/fhir/parser/StrictErrorHandler.html">StrictErrorHandler</a>
-					throws a <code>DataFormatException</code> if any errors are detected.
+					throws a
+					<code>DataFormatException</code>
+					if any errors are detected.
 				</li>
 			</ul>
-			
+
 			<p>
-				The following example shows how to configure a parser to use strict validation. 
+				The following example shows how to configure a parser to use strict validation.
 			</p>
 			<macro name="snippet">
 				<param name="id" value="parserValidation" />
 				<param name="file" value="examples/src/main/java/example/ValidatorExamples.java" />
 			</macro>
-			
+
 			<p>
 				You can also configure the error handler at the FhirContext level, which is useful
-				for clients. 
+				for clients.
 			</p>
 			<macro name="snippet">
 				<param name="id" value="clientValidation" />
 				<param name="file" value="examples/src/main/java/example/ValidatorExamples.java" />
 			</macro>
-			
+
 			<p>
-				FhirContext level validators can also be useful on servers. 
+				FhirContext level validators can also be useful on servers.
 			</p>
 			<macro name="snippet">
 				<param name="id" value="serverValidation" />
@@ -87,7 +98,9 @@
 
 			<p>
 				HAPI provides a built-in and configurable mechanism for validating resources.
-				This mechanism is called the <i>Resource Validator</i>.
+				This mechanism is called the
+				<i>Resource Validator</i>
+				.
 			</p>
 
 			<p>
@@ -102,38 +115,42 @@
 			</p>
 
 			<subsection name="Preparation">
-				
+
 				<p>
-					In order to use HAPI's Schematron support, a libaray called 
+					In order to use HAPI's Schematron support, a libaray called
 					<a href="https://code.google.com/p/phloc-schematron/">Phloc-Schematron</a>
 					is used, so this library must be added to your classpath (or Maven POM file, Gradle
 					file, etc.)
-					Note that this library is specified as an optional dependency by HAPI FHIR
+					Note that this library is specified as an optional dependency
+					by HAPI FHIR
 					so you need to explicitly include it if you want to use this
-					functionality. 
+					functionality.
 				</p>
 				<p>
-					See <a href="./download.html">Downloads</a> for more information on how
+					See
+					<a href="./download.html">Downloads</a>
+					for more information on how
 					to add it.
 				</p>
 			</subsection>
-			
+
 			<subsection name="Validating a Resource">
-				
+
 				<p>
 					To validate a resource instance, a new validator instance is requested
 					from the FHIR Context. This validator is then applied against
-					a specific resource instance, as shown in the example below.
+					a specific resource
+					instance, as shown in the example below.
 				</p>
 				<macro name="snippet">
 					<param name="id" value="basicValidation" />
 					<param name="file" value="examples/src/main/java/example/ValidatorExamples.java" />
 				</macro>
-						
+
 			</subsection>
 
 			<subsection name="Validating a Set of Files">
-				
+
 				<p>
 					The following example shows how to load a set of resources from files
 					on disk and validate each one.
@@ -142,51 +159,100 @@
 					<param name="id" value="validateFiles" />
 					<param name="file" value="examples/src/main/java/example/ValidatorExamples.java" />
 				</macro>
-						
+
 			</subsection>
 
-		<a name="structure_definition_validation"/>
+			<a name="structure_definition_validation" />
 		</section>
-		
+
-		<section name="Resource Validation (StructureDefinition / ValueSet)">
+		<section name="Resource Validation (Profile/StructureDefinition)">
-			
+
 			<p>
 				As of HAPI FHIR 1.2, HAPI supports validation against StructureDefinition
 				resources. This functionality uses the HL7 "InstanceValidator", which is able
-				to check a resource for conformance to a given profile (StructureDefinition),
+				to
-				including validating codes for conformance to their given ValueSets. 
+				check a resource for conformance to a given profile
+				(StructureDefinitions and ValueSets),
+				including validating fields, extensions, and codes for conformance to their given ValueSets.
 			</p>
 			<p>
 				StructureDefinition validation can be used to validate a resource against the
 				official structure definitions (produced by HL7) as well as against custom
 				definitions provided either by HL7 or by the user.
 			</p>
-			
+
 			<subsection name="Preparation">
-				
+
 				<p>
 					To use this functionality, you must add the following two dependencies
-					to your classpath (or Maven POM file, Gradle file, etc.): 
+					to your classpath (or Maven POM file, Gradle file, etc.):
 				</p>
 				<ul>
 					<li>
-						<b>hapi-fhir-structures-hl7org-dstu2</b>: This file contains the "reference implementation"
+						<b>hapi-fhir-structures-hl7org-dstu2</b>
-						structures and tooling. You need to include it even if you are not using the RI model 
+						: This file contains the "reference implementation"
+						structures and tooling. You need to include it even if you are not using the RI model
 						(the StructureDefinition validation will work against HAPI structures as well)
 					</li>
 					<li>
-						<b>hapi-fhir-validation-resources-dstu2</b>: This file contains the official FHIR
+						<b>hapi-fhir-validation-resources-dstu2</b>
+						: This file contains the official FHIR
 						StructureDefinition files, and the ValueSets needed to support them.
 					</li>
 				</ul>
 				<p>
-					See the <a href="./download.html">download page</a> for more information.
+					See the
+					<a href="./download.html">download page</a>
+					for more information.
 				</p>
 
 			</subsection>
+
+			<subsection name="Running the Validator">
+
+				<p>
+					To execute the validator, you simply create an instance of
+					<a href="./apidocs-hl7org-dstu2/ca/uhn/fhir/validation/FhirInstanceValidator.html">FhirInstanceValidator</a>
+					and register it to new validator, as shown in the example below.
+				</p>
+				
+				<p>
+					Note that the example below uses the official FHIR StructureDefintions and ValueSets
+					to validate the resource. It will not work unless you include the 
+					<code>hapi-fhir-validation-resources-[version].jar</code> to your classpath.
+				</p>
+				
+				<macro name="snippet">
+					<param name="id" value="instanceValidator" />
+					<param name="file" value="examples/src/main/java/example/ValidatorExamples.java" />
+				</macro>
+
+			</subsection>
+
+			<subsection name="Supplying your own StructureDefinitions">
+				
+				<p>
+					The FhirInstanceValidator relies on the 
+					<a href="./apidocs-hl7org-dstu2/ca/uhn/fhir/validation/IValidationSupport.html">IValidationSupport</a>
+					interface to load StructureDefinitions, and validate codes. 
+				</p>
+				<p>
+					By default, the
+					<a href="./apidocs-hl7org-dstu2/ca/uhn/fhir/validation/DefaultProfileValidationSupport.html">DefaultProfileValidationSupport</a>
+					implementation is used. This implementation loads the FHIR profiles from the
+					validator resources JAR. If you want to use your own profiles, you may wish to
+					supply your own implementation. 
+				</p>
+
+				<macro name="snippet">
+					<param name="id" value="instanceValidatorCustom" />
+					<param name="file" value="examples/src/main/java/example/ValidatorExamples.java" />
+				</macro>
 			
+			</subsection>
+
 		</section>
-		
+
 	</body>
 
 </document>