search

itplr-kosit / validator

Validates XML documents with XML Schema and Schematron
Apache License 2.0
77 stars 40 forks source link

Better return object of check for library use #27

Closed JannickWeisshaupt closed 5 years ago

JannickWeisshaupt commented 5 years ago

At the moment the return type of defaultCheck.check is Document, which is a representation of the xml report. For a developer it is now non obvious whether the xRechnung was invalid and should be rejected or valid and can be forwarded. It follows a non complete list of useful methods for a better return object.

boolean isAcceptRecommendation() Document getReport() String or DOM etc. getReportAsHtml() List getValidationResult(): list of all validation steps with their result

apenski commented 5 years ago

This is good idea. We focused too much on the standalone usage, since most of the users were not interested in library usage yet.

Regarding getReportAsHtml(): We have no knowledge about the actual result document format, there could be html, there could be xml with one or many html elements/fragments. The standalone version therefore provides a switch to extract all html nodes to files. Do you mean such an extraction process behind this method? Or do you have a specific configuration / result document type in mind where you have exactly one html report within the report document?

Anyway I would rather prefer:

List<Nodes> extractHTMLNodes or similiar

Regarding getValidationResult(): what would be your expectation? e.g. how many technical details would you expect? All e.g. schematron violations? Or would it be sufficient to have the information which step fail?

@rkottmann so we need to discuss whether we introduce a api breaking change or how we can extend the current one

JannickWeisshaupt commented 5 years ago

Regarding getReportAsHtml(): We have no knowledge about the actual result document format, there could be html, there could be xml with one or many html elements/fragments. The standalone version therefore provides a switch to extract all html nodes to files. Do you mean such an extraction process behind this method? Or do you have a specific configuration / result document type in mind where you have exactly one html report within the report document?

Well I forgot that the report format depends on my own configuration. Taking that into mind it would be nice to just have a method that returns just the report that is specified so I guess

Anyway I would rather prefer: List extractHTMLNodes or similiar

would be fine, with maybe an easy way to convert it to string, so e.g. a toString method.

Regarding getValidationResult(): what would be your expectation? e.g. how many technical details would you expect? All e.g. schematron violations? Or would it be sufficient to have the information which step fail?

I am not really sure but something that allows you to collect all problems within the xRechnung so that the supplier can be informed. I would suggest:

List getValidationResults()

// validation result of a single schematron or xmlSchema validation
class ValidationResult
{
  boolean isValid
  List<ValidationViolation> // empty if valid, otherwise contains all causes for the violation e.g. as string or new object
}
throatwobbler commented 5 years ago

This feature (something like getViolations()) is definitely a must-have. Our company has to develop an application for a customer who wants to check the xRechnung and automatically deny or forward it depending on the outcome of the check. Right now I have no idea if or how this can be done with the current validator. I guess we have to implement this feature by ourselves since xRechnung will be mandatory soon.

apenski commented 5 years ago

@throatwobbler For the moment you can wrap the result document and query for appropriate elements in the report e.g. with xpath-expression or DOM traversal.

We'll discuss this enhancement. Currently the validator internally has no information about failed schematron asserts. It just hands over the result to the report generating stylesheet. And since the validator is not only meant for xrechnung we need to consider different scenarios.

But we are actively developing the validator at the moment and will prepare new releases until summer. Stay tuned.

throatwobbler commented 5 years ago

Wouldn't your solution make the implementation dependent from the xsl stylesheet that generates the report? Maybe even dependent from the exact wording of the warning/error messages?

I think we will have to give this a try because our tight time schedule probably does not allow for a complete new implementation of these checks.

Thanks! And I will definitely stay tuned to see how this project evolves.

apenski commented 5 years ago

yes, this would depend on the actual report generating stylesheet, but is the only workaround I see for the moment, with current validator implementation

fsteimke commented 5 years ago

The stylesheet has to generate a report which must be valid with respect to the report.xsd schema. Otherwise it is a misconfiguration. This has to be checked and guaranteed by the validator engine. All report-generating stylesheets in known configuratios here at github satisfy this condition, e. g. the configuration for eInvoice.

Based on this assumption we can find all the information that is needed at fixed places, Independent from the particular stylesheet.

As far as i can see, we already have everything that could be needed for this issue. Of course, an api method is needed which returns the whole report, not only parts of it.

apenski commented 5 years ago

We are currently working on an API interface. See Result.java for details. Additionally the default implementation of the API inteface allows some more functionality if needed. E.g.:

These are not in API yet, since we want to keep interface as small as possible for the moment. They can be propagated to the interface if the functionality is broader used. Any hints and wishes are welcome ;)

apenski commented 5 years ago

@fsteimke so we now have a basic API abstraction which can be used in custom projects to validate xml input.

If I understand your last point right, you proposal is beyond a simple return object for the current architecture. Furthermore you want a general/generic report format of the validator which carries the custom/human readable report.

For the moment the report format is not known to this validator. This was an architectoral decision. Introducing a defined report format would break backward compatiblity. But I see your point and I see some advantages.

I guess you are in contact to @rkottmann and @fbuettner-hb to further discuss this change ;)

svanteschubert commented 5 years ago

Allow me to exaggerate in my suggestion:

Input API

For the interface of input of validation problems, remember that SAX Errorhandler Interface, is not only for XML errors (I quote from above: 'Also parsers may throw appropriate exceptions for non-XML errors.') For instance, our ODF Validator implements a default error handler, which also collects ODF ZIP problems as mentioned in the ODF specification, basically all validation problems. NOTE: Although XRechnung is only XML, there might be BASE64 attachments, which might be for some clients as well be valideted.

What I did not realize instantly and I would like to point out is that specifications always use two conformance levels by phrases, which are mapped to the interface:

  1. "may/should" -> if not used in document-to-be-validated maps to warning and
  2. "must/shall not" -> if not used maps to error
  3. "fatal error" -> is when it is impossible to continue, like loading an Excel file instead of XRechnung

Output API

In general, there are three important output interfaces to me:

  1. HTML interface (e.g. ODF validator projects generated a Java WAR file for the end-user. The WAR includes a simple front-end to be added to any Java Application Server), like in action https://odfvalidator.org/. Note: The W3C combined all their former validators into one validator unicorn: https://validator.w3.org/unicorn/ with a nice translation unit. The HTML comes often with a reference to the validation rule (specificaiton) to be checked.
  2. Command line interface for batch processing in Unit Tests (e.g. ODF Validator an LibreOffice)
  3. Programmatic JAVA API to receive the detailed errors for other dependent applications.

Modularity & Reuse

It would be most helpful for modularity, if all UI interfaces would receive the same input from the core validator and just add UI information differently. By this future UI endpoints could be added.

Unfortunately, there is not yet an open-source validator framework that can be used out-of-the-box for all - at least "file format" - validators, although their interfaces do not vary that much. (Without checked in detail, my guess is W3C unicorn validators / ODF validator / XRechnung validator can share a lot of basic validation functionality). Everyone implements their own basic functionality.

Possible Future Requirements for EN16931 Validators

Just imagine: "What if the future there should be not only a XRechnung (CIUS) validator, but a rather a generic validator for any EN16931 sub- (CIUS) or superset (EXTENSION) across Europe, as long a machine readable CIUS/extension information-set with all required informations for the validator is being provided?"

This is a lot of sci-fi, but perhaps some of the API decisions with this high-end requirements in the back of your mind make decicisons more reusable for the future... ;-)

Cheers, Svante

PS: ODF Validator design is quite old as well and was worked out before I realized the above (as part of an EU validation project application), therefore the ODF validator is not the best example. But I might be willing to assist your refactoring, when I start using your validator as part of a client project.. ;-)

rkottmann commented 5 years ago

We just released version 1.1.0 of the validator. This should adress 99% of the orignal request of @JannickWeisshaupt. Please hav e a look at https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Result.java

rkottmann commented 5 years ago

In answer to @svanteschubert

  1. the validator is a generic validation tool for any xml
  2. We have separated the engine (validator) from the configurations of which there are currently xrechnung and xgewerbeanzeige
  3. Hence we welcome more configurations e.g. for other CIUSs and Extensions as for any kind of other XML
rkottmann commented 5 years ago

In general it is important to differentiate the discussion about the JAVA API the validator offers and the general contract between the validator and the configurations.

With the 1.1.0 release, we enhanced the Java API hopefully to your satisfaction (any more issue reports are welcome).

In answer to @svanteschubert we already have a CLI and API interface well defined. Although I am not sure about the value of an HTML interface, we will work on that, especially w.r.t. contract between the validator and the configurations.

And also thanks to @throatwobbler comment, we will sharpen the contract between the validator and the configurations in the next release.

This contract will be based and clear and simple XML Schema and will be much better documented .

Now closing this discussion.

thx for all your valuable comments