Page MenuHomePhabricator

Provide an additional endpoint with more detailed translation output
Closed, ResolvedPublicFeature

Description

Feature summary (what you would like to be able to do and where):

Consider providing an additional endpoint for Web2Cit-Server that provides a more detailed translation output, including:

  • The individual outputs for all selection and transformation steps
  • The procedure output for each field and whether it is a valid or invalid output
  • Possibly, what other templates of the same path pattern group would have returned

Use case(s) (list the steps that you performed to discover that problem, and describe the actual underlying problem which you want to solve. Do not describe only a solution):

Until the Web2Cit-Editor (=frontend) is implemented, some users may be willing to start testing the system by manually defining template and pattern definitions in our storage in Meta, and asking the Web2Cit-Server to pick them up and translate some URLs. However, in many cases it may be difficult to understand why a translation is not returning the expected results. Is it bug? Or are the definitions wrong?

Benefits (why should this be implemented?):

Having a (maybe temporary) additional endpoint that shows the intermediate outputs would help understand a translation output.

Event Timeline

diegodlh triaged this task as High priority.Apr 1 2022, 1:16 PM

A debug endpoint has been implemented in the "debug" branch, with ec243426.

Debugging invalid definitions

However, we still have a blind spot in cases where a template definition fails validation. For example, if the fieldname is invalid. Some of these cases would not be detected by our JSON-schemas, since they do not include validation of string values.

In these cases, the whole template would be ignored, and users may have a hard time identifying why. It has been proposed that individual misformatted elements be ignored (instead of the whole template), see T305267; and that further information be provided regarding why a specific definition may be wrong, see T302425.

In some cases, misformatted definitions may even result in server errors, as described in T305269.

isArray field property

Template fields have an isArray property indicating whether the field expects a single value, or an array of values.

Include the value of this property in the debug information, since it would help understand why an array procedure output is being joined (if isArray = true) to become the field output (consider addressing T302024 first).

Endpoint discoverability

To make the debug endpoint more discoverable, add a link at the end of the result page returned by the standard or sandbox endpoints:

"Not what you expected? Use our debug endpoint (link) to find out why"

Regarding debugging invalid definitions, some cases have been covered via T305267:

  • fields with invalid fieldnames are ignored
  • selection/transformation steps with invalid types or configs are ignored

Other cases may be pending. For example, if a template is missing one of the mandatory fields, the template is silently ignored.

Regarding including the isArray property, that would require changing Web2Cit-Core, because the FieldInfo type does not include this. The same thing happens with the pattern property. Because this debug endpoint is meant to be temporary, I have just included a link to our early adopter guidelines as a workaround.

Pending:

  • Update early adopter guidelines
  • Notify Advisory Board
diegodlh claimed this task.