HPCC-22655 Update ESDL auth_feature documentation by g-pan · Pull Request #21025 · hpcc-systems/HPCC-Platform

g-pan · 2026-02-25T14:30:33Z

Type of change:

This change is a bug fix (non-breaking change which fixes an issue).
This change is a new feature (non-breaking change which adds functionality).
This change improves the code (refactor or other change that does not change the functionality)
This change fixes warnings (the fix does not alter the functionality or the generated code)
This change is a breaking change (fix or feature that will cause existing behavior to change).
This change alters the query API (existing queries will have to be recompiled)

Checklist:

Smoketest:

Send notifications about my Pull Request position in Smoketest queue.
Test my draft Pull Request.

Testing:

Successful Unit Testing: https://github.com/g-pan/github-action-dev-build/actions/runs/22373126789
(formatted PDF files available from the Artifacts there)

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

github-actions · 2026-02-25T14:30:56Z

Jira Issue: https://hpccsystems.atlassian.net//browse/HPCC-22655

Jirabot Action Result:
Workflow Transition To: Merge Pending
Additional PR: #21025

Copilot

Pull request overview

This PR updates the ESDL auth_feature documentation to provide comprehensive technical specification of feature-level security configuration in ESDL services and methods.

Changes:

Expanded documentation from basic usage to comprehensive technical reference
Added formal BNF syntax specification and token semantics
Included detailed examples demonstrating service and method-level authentication patterns

Comments suppressed due to low confidence (3)

docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml:10

DocBook uses <literal> for code elements, not <code>. Replace <code>ESPservice</code> with <literal>ESPservice</literal> and <code>ESPmethod</code> with <literal>ESPmethod</literal> to match DocBook conventions and maintain consistency with the rest of the document where <literal> is used for similar elements.

    The <emphasis>auth_feature</emphasis> attribute configures feature-level security in ESDL by associating features and access levels to <code>ESPservice</code> and <code>ESPmethod</code> elements. This provides fine-grained, declarative access control for ESDL services and methods.

docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml:19

DocBook uses <literal> for code elements, not <code>. Replace all instances of <code> with <literal> in this line: ESPservice, EsdlService, ESPmethod, and EsdlMethod.

      <code>ESPservice</code> values take effect at the <code>EsdlService</code> scope, while <code>ESPmethod</code> values are in the <code>EsdlMethod</code> scope and override service scope requirements. If <emphasis>auth_feature</emphasis> is set on both service and method, the resulting security requirement is the union, with method-level tokens taking precedence where conflicts arise.

docs/EN_US/DynamicESDL/DESDL-Mods/ESDLauth_feature.xml:208

Corrected 'full access-level' to 'full access level' (removed hyphen between 'access' and 'level').

    ; a new map entry is created that requires full access-level

JamesDeFabia

Formatting is almost there

JamesDeFabia · 2026-03-04T20:39:54Z

-  <para><indexterm>
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<sect1 id="ESDL_AuthFeature">
+  <title>ESDL auth_feature: Semantics and Syntax</title>


Title should be "auth_feature"
Look at the other attributes in the book. This one should be the same. For example, see max_ver on page 34.

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

github-actions · 2026-03-17T16:35:18Z

🔄 Upmerge Test Results

Status: ✅ All branches merged successfully
PR: #21025 - HPCC-22655 Update ESDL auth_feature documentation
Base Branch: candidate-10.2.x
Test Time: 2026-03-17 15:48:29 UTC

✅ Successful Branches (1)

master
This comment was automatically generated by the upmerge test workflow.

JamesDeFabia

The formatting is still very different than all the other similar topics. Look at the PDF.

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

github-actions · 2026-03-23T19:21:08Z

🔄 Upmerge Test Results

Status: ✅ All branches merged successfully
PR: #21025 - HPCC-22655 Update ESDL auth_feature documentation
Base Branch: candidate-10.2.x
Test Time: 2026-03-23 19:20:51 UTC

✅ Successful Branches (1)

master
This comment was automatically generated by the upmerge test workflow.

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

github-actions · 2026-03-23T21:38:31Z

🔄 Upmerge Test Results

Status: ✅ All branches merged successfully
PR: #21025 - HPCC-22655 Update ESDL auth_feature documentation
Base Branch: candidate-10.2.x
Test Time: 2026-03-23 21:01:52 UTC

✅ Successful Branches (1)

master
This comment was automatically generated by the upmerge test workflow.

JamesDeFabia

Couple of comments inline

JamesDeFabia · 2026-04-06T16:32:07Z

+  service level by its own <emphasis>auth_feature</emphasis> string.</para>
+
+  <para><emphasis role="bold">See Also: </emphasis> <link
+  linkend="ESDLESPservice">ESPservice</link>, <link


Two of these three links do not work in the rendered PDF.

JamesDeFabia · 2026-04-06T16:33:48Z

-    ]
-   MyMethod2(MyMethod2Request, MyMethod2Response);
- };</programlisting>
+    </indexterm> The <emphasis>auth_feature</emphasis> attribute configures


This line begins with a space, causing it to appear indented in the PDF

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

github-actions · 2026-04-06T18:57:46Z

🔄 Upmerge Test Results

Status: ✅ All branches merged successfully
PR: #21025 - HPCC-22655 Update ESDL auth_feature documentation
Base Branch: candidate-10.2.x
Test Time: 2026-04-06 18:57:31 UTC

✅ Successful Branches (1)

master
This comment was automatically generated by the upmerge test workflow.

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

github-actions · 2026-04-06T20:07:54Z

🔄 Upmerge Test Results

Status: ✅ All branches merged successfully
PR: #21025 - HPCC-22655 Update ESDL auth_feature documentation
Base Branch: candidate-10.2.x
Test Time: 2026-04-06 20:07:37 UTC

✅ Successful Branches (1)

master
This comment was automatically generated by the upmerge test workflow.

JamesDeFabia

Still one broken link. See comment inline

JamesDeFabia · 2026-04-06T21:57:34Z

+
+  <para><emphasis role="bold">See Also: </emphasis> <link
+  linkend="EPservice">ESPservice</link>, <link
+  linkend="ESPmethod">ESPmethod</link>, <link linkend="ESDL_Attributes">ESDL


The last link (ESDL Attributes) does not work in the rendered PDF. However, I am not sure there needs to be a link to that section from this topic. You can either delete it or fix it.

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

github-actions · 2026-04-07T11:43:17Z

🔄 Upmerge Test Results

Status: ✅ All branches merged successfully
PR: #21025 - HPCC-22655 Update ESDL auth_feature documentation
Base Branch: candidate-10.2.x
Test Time: 2026-04-07 11:39:54 UTC

✅ Successful Branches (1)

master
This comment was automatically generated by the upmerge test workflow.

JamesDeFabia

Looks good from my POV

timothyklemm · 2026-04-08T14:22:40Z

+feature-name ::= ( feature-name-char* '${' variable-name '}' feature-name-char* | feature-name-char+ )
+    ; feature-name-char is any char except whitespace, ',', '"', '!', or ':'
+    ; feature-name has the added restrictions of not being a reserved-word
+variable-name ::= ( 'SERVICE' | 'METHOD' ) </programlisting>


This is not a program listing. It's a variation of a standard notation describing how the attribute value is assembled/interpreted. No part of it is meant to be copied and pasted by a user as a code sample.

Any line beginning with ';' is a comment. These do not need to be presented in code style, except for text between back ticks. Feel free to format the lines as anything but code and, more importantly, line preservation is not required. Multiple comments are truncated by strictly preserving lines.

timothyklemm · 2026-04-08T14:23:22Z

+  <para><emphasis role="bold">Note:</emphasis> The method scope overtakes the
+  service scope: a method may override any or all requirements set at the
+  service level by its own <emphasis>auth_feature</emphasis> string.</para>


It's an important note but probably not worth repeating.

timothyklemm · 2026-04-08T14:26:31Z

+
+  <para><code>ESPservice</code> values take effect at the
+  <code>EsdlService</code> scope, while <code>ESPmethod</code> values are in
+  the <code>EsdlMethod</code> scope and override service scope requirements.


... and may either extend or override service scope requirements.

The next sentence does reflect this, but it feels contradictory as written.

timothyklemm · 2026-04-08T14:32:50Z

+  resulting security requirement is the union, with method-level tokens taking
+  precedence where conflicts arise.</para>
+
+  <para>See the formal BNF specification and parsing details for precise


Similar to BNF, but may be better to not call it that.

timothyklemm · 2026-04-08T14:44:57Z

+          <entry><literal>!X</literal> (where X is any value)</entry>
+
+          <entry>Reserved for future semantics; constraints on X to be
+          defined. New syntax.</entry>


It is used. If you look in the formal syntax, it can negate all lower precedence settings (X is empty or ::), a lower precedence scope (X is a defined scope name), or a lower precedence feature (X is [ optional scope ] :: feature name).

timothyklemm · 2026-04-08T14:48:06Z

- };</programlisting>
+    </indexterm>The <emphasis>auth_feature</emphasis> attribute configures
+  feature-level security in ESDL by associating features and access levels to
+  <code>ESPservice</code> and <code>ESPmethod</code> elements. This provides


The formal syntax refers to scope-name, which comes into play when discussing overriding settings. It may be good to associate scopes to the elements mentioned.

add note: that this scope could relate

timothyklemm · 2026-04-08T14:55:38Z

+    ; a new map entry is created specifying the named feature and the given access level
+    ; the security state is affirmed
+scope-name ::= ( 'DEFAULT' | 'ESDLSERVICE' | 'ESDLMETHOD' | ... )
+    ; additional names are anticipated resulting from binding integration


The defined scopes for ecm defined features are: EsdlServie and EsdlMethod. DESDL adds BindingService and BindingMethod to the list. All values are case insensitive. The DESDL extensions have higher precedence than the ecm values, meaning EsdlService can be overridden by EsdlMethod, which can be overridden by BindingService, which can be overridden by BindingMethod.

this : The DESDL extensions have higher precedence than the ecm values, meaning EsdlService can be overridden by EsdlMethod, which can be overridden by BindingService, which can be overridden by BindingMethod. : better description

key is that DESDL introduces 2 additional scopes (and the key is you can 'override' ancestor scopes)

timothyklemm · 2026-04-08T15:34:33Z

+ESPservice [auth_feature("DataAccess:Full")] DataService
+{
+  ESPmethod GetData(GetDataRequest, GetDataResponse);
+  ESPmethod [auth_feature("DataAccess:None")] GetPublicData(GetPublicDataRequest, GetPublicDataResponse);


Consider splitting into multiple lines to improve appearance. Text extends beyond block background.

HPCC-22655 Update ESDL auth_feature documentation

01d37bd

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

g-pan requested review from JamesDeFabia, Copilot and timothyklemm February 25, 2026 14:30

Copilot started reviewing on behalf of g-pan February 25, 2026 14:35 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

JamesDeFabia requested changes Mar 4, 2026

View reviewed changes

HPCC-22655 Update ESDL auth_feature documentation

cd5c8a8

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

g-pan requested a review from JamesDeFabia March 19, 2026 13:41

JamesDeFabia requested changes Mar 20, 2026

View reviewed changes

HPCC-22655 Update ESDL auth_feature documentation

03f95e2

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

HPCC-22655 Update ESDL auth_feature documentation

950f919

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

g-pan requested a review from JamesDeFabia April 6, 2026 16:21

JamesDeFabia requested changes Apr 6, 2026

View reviewed changes

HPCC-22655 Updates to the AuthFeature

cf48b58

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

HPCC-22655 Update ESDL auth_feature documentation

8dc9bcb

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

g-pan requested a review from JamesDeFabia April 6, 2026 20:09

JamesDeFabia requested changes Apr 6, 2026

View reviewed changes

HPCC-22655 Update ESDL auth_feature documentation

eae8d89

Signed-off-by: Panagiotatos <greg.panagiotatos+copilot@lexisnexisrisk.com>

g-pan requested a review from JamesDeFabia April 7, 2026 11:39

JamesDeFabia approved these changes Apr 7, 2026

View reviewed changes

timothyklemm requested changes Apr 8, 2026

View reviewed changes

Conversation

g-pan commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of change:

Checklist:

Smoketest:

Testing:

Uh oh!

github-actions Bot commented Feb 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

JamesDeFabia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 17, 2026

🔄 Upmerge Test Results

✅ Successful Branches (1)

Uh oh!

JamesDeFabia left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 23, 2026

🔄 Upmerge Test Results

✅ Successful Branches (1)

Uh oh!

github-actions Bot commented Mar 23, 2026

🔄 Upmerge Test Results

✅ Successful Branches (1)

Uh oh!

JamesDeFabia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 6, 2026

🔄 Upmerge Test Results

✅ Successful Branches (1)

Uh oh!

github-actions Bot commented Apr 6, 2026

🔄 Upmerge Test Results

✅ Successful Branches (1)

Uh oh!

JamesDeFabia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 7, 2026

🔄 Upmerge Test Results

✅ Successful Branches (1)

Uh oh!

JamesDeFabia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

g-pan commented Feb 25, 2026 •

edited

Loading