sap / abap-file-formats Goto Github PK

How shall we handle metadata which is only needed for the deployment of software (e.g., using gCTS), but not during design-time?

Change is constant, so over time, some fields in the JSON schemas might be moved/removed/added

Any considerations regarding versioning? eg. does a JSON file follow the old or new schema of an object

in abapGit we add https://github.com/abapGit-tests/VIEW/blob/main/src/zag_unit_testv.view.xml#L2 so that its possible for the code reading the file can make assumptions regarding the content

https://github.com/SAP/abap-file-formats/blob/main/file-formats/intf/format.md,

zif_aff_example.intf.abap

and https://github.com/SAP/abap-file-formats/blob/main/file-formats/clas/format.md

zcl_aff_example.clas.global.abap

personally I would expect the filename scheme for the main/global ABAP file to be identical for INTF and CLAS objects

When creating and editing in Eclipse, both objects look similar to the developer?

I suggest removing ".global." from the CLAS filename

Looks like there is some double maintenance?

Suggest keeping the README short

Shouldn't we have a branch protection rule on main? I cannot configure it due to some central restriction...

Agree, we can VALIDATE_ALL_CODEBASE and apply the slim-image provided by the linter https://github.com/github/super-linter/#slim-image

Originally posted by @albertmink in #132 (comment)

fields mainObjectType and mainObjectName should be string instead of boolean in the schema,

If 5 different people writes a serializer, it will be nice if they can come up with identical binary files if based on identical objects.

git uses a checksum of the file, so if the files are not binary identical they are considered different :)

Suggest adding:

• Codepage, presumably UTF-8
• Should files have byte order mark or not?
• Carriage returns for newlines?
• Newline at end of file(note that the ABAP editor has some logic)
• JSON indentation(2 spaces?)

a namespace in a ABAP system is eg. /nspc/, having "/" part of filenames will give trouble on most filesystems(?)

so it must be escaped/changed/avoided somehow

The .json file format does not allow comments

However, .jsonc and .json5 does allow comments

Consider if the extension of JSON should allow for comments or not

Personally I find it difficult to manually maintain JSON schemas, there will also be some reuse between definitions(eg the language field), so I like to define this semantically instead of manually editing the schemas.

To solve this I like to maintain json schemas as TypeScript, and then use https://github.com/vega/ts-json-schema-generator to generate the JSON schemas.

I can try making a small example?

Example: https://github.com/SAP/abap-file-formats/tree/main/file-formats/chkc

it contains

the source is under type and the first file in the folder is the auto generated json schema file

Suggest:
A: Move the ABAP source to the root of the object type folder
B: Move the auto generated json schema to a new folder generated under the object type
C: Change the filename of the auto generated json schema, eg zif_atc_aff_chkc_v1.json to make it easier for users to tell the relationship between files

This is a little nit-picky, but I think Github really doesn't like tooling to reference https://raw.githubusercontent.com. I'd suggest using Github Pages or another system to publish the schema files onto a CDN-backed infrastructure and bake that URL into the schemas so that it doesn't have to change in the future. I'd guess that SAP will eventually want to host these somewhere under sap.com.

ie. when a new version is required

I dont remember if developers are used to editing .properties in Eclipse?

File formats will keep changing forever, so I do not partially have a favorite. However, I like to stick to as few formats as possible

Can JSON be used instead of .properties? that way there is just one type of metadata format

Also, YAML is popular, TOML etc.

should we install the GH APP for abaplint?

Suggest setting the merge button to be squash(under repo settings)

this will give fewer commits in the main branch, one commit per PR merge

Hi,
I have not used enums very much, so I looked into how it works,

https://blogs.sap.com/2016/10/10/abap-news-release-7.51-enumerations/

notably "Normally, you are not interested in the contents of an enumerated object at all."

in abap-file-formats we are interested in the values, eg setting a json value,

TYPES:
  basetype TYPE c LENGTH 1,
  BEGIN OF ENUM ver BASE TYPE basetype,
    standard          VALUE IS INITIAL,
    cloud_development VALUE '5',
  END OF ENUM ver.

DATA: BEGIN OF ls_json,
        ver TYPE basetype,
      END OF ls_json.
ls_json-ver = cloud_development.
WRITE ls_json-ver.

Which outputs "C" when run

As we are interested in values, probably using structured constants is the better approach?

https://github.com/SAP/abap-file-formats/blob/main/doc/specification.md#file-names

ABAP should go into ABAP files, one file, like its presented to the developer in Eclipse

Metadata for a object(R3TR) should go into a single metadata file per object, having eg. one metadata file per dynpro, per CUA etc. makes it more complex IMHO, more schemas, more things to check on serialization/deserialization time

Translations: something, I've not thought much about these yet, deferred to #106

We have to define how we represent documentation (especially SAPscript) in ABAP file formats.

Questions are from my point of view:

1. Technical (using two columns like in classic SAPscript editor) or representation in a dedicated file format which is close to documentation
2. Is the documentation part of the Json or dedicated files (relates also to #115)

The schema for object type NROB is not based on an ABAP type, yet.

The SAP team plans to address the following issues in our 2nd iteration (sprint) in July 2021:

• #117
• #119

The iteration lasts 2 weeks and ends on August 2, 2021.

What indentation do we want to use for the JSON files and schema? Suggestion would be 2 or 4 spaces.

We have to clarify what $schema we are refering to in the serialized files:

• "$schema": "http://github.com/SAP/abap-file-formats/file-formats/clas/clas.json"
• "$schema": "https://github.com/SAP/abap-file-formats/blob/main/file-formats/clas/clas.json"
• link to completely something different: schemastore.org/abap_clas.json (just as a mirror, to make access easier)

See:
#11 (comment)

The field abapLanguageVersion is really difficult

In other programming languages, the actual version of the language is rarely(?) part of the actual source code. Instead the author states the version requirements in a README (I'm thinking about Java/JavaScript/TypeScript/C++)

There is also "integrated Steampunk" which will be out sometime and do something 😄 Will a 5 year old integrated steampunk have the same languageversion as the latest cloud steampunk? I'm afraid that the list will keep increasing over time unless the purpose of the field is defined very clearly.

CHKO is in itself "Metadata of ATC Check Object", but "The files don't contain metadata"

I have not encountered a CHKO in the wild, so I'm not really sure what it is. But in the traditional SCI setup, the code inspector check defines the actual metadata, perhaps a CHKO is something that is generated behind the scenes?

Do the developer create the CHKO manually?

Right now I think its difficult to tell the direction, as the main branch contains both the old approach(manual json schema) and new approach(auto generated from ABAP)

Suggest removing the old examples, store it in a separate branch or in open issues for each object type

Is defining directory/folder structure in scope?

Like in Java, a project typically consists of a folder structure, where each folder contains multiple objects

Remove the github action that validates JSON syntax and JSON instances by deleting files

• json-validator.py
• requirements.txt
• .github/py-validation.yml

https://github.com/SAP/abap-file-formats/blob/main/file-formats/clas/examples/zcl_aff_example.clas.json

Suggest moving types + attributes + events + methods under a field named "descriptions", as eg. adding a type under types does not actually add a type in the class, but only sets a description, which will take effect if the code contains the type?

The schema for object type ENHS is not based on an ABAP type, yet.

boolean values should be false instead of "false"

plus property fallbackClass missing

masterLanguage is part of multiple files, and it is defined as 2 characters

but what is considered correct, and what is wrong?

In SAP all user formatted languages are 2 characters upper case, but looking at something like ISO its 2 character lower case

Suggest to make an explicit enum list of allowed values

see #29

from the readme,
"Object Name corresponds to the name of the ABAP object."

what is an ABAP object?

My guess would be the objects defined in TADIR on R3TR level, but the readme also mentions LIMU

LIMU does not guarantee unique naming, so I'd suggest only considering R3TR

Say, I create a JSON schema for the ACID object type, will it as such be accepted into main?

There are 1000+ different object types(?), and each object type has an owner inside SAP(?)

The schema for object type ENHO is not based on an ABAP type, yet.

Hi,
I think its safe to set uniqueItems for all arrays?

https://json-schema.org/understanding-json-schema/reference/array.html#uniqueness

suggest:

• add comment regarding the schema version
• add comment regarding use of lowerCamelCase(?) for naming of JSON fields

we currently have:

zif_oo_aff_intf_v1.intf.abap
zif_atc_aff_chkc_v1.intf.abap

INTF and CHKC are the TADIR R3TR names, which are guaranteed to be unique, I suggest leaving out the "_oo" and "_atc" parts

we can talk about this in the next call

add comment in auto generated files that they are auto generated, ie. should not be edited manually

• We applied several different casing styles in json block:
  

  abap-file-formats/file-formats/clas/clas.json

  Line 155 in af51e5e

  "title": "Attribute Name",

  
  

  abap-file-formats/file-formats/clas/clas.json

  Line 161 in af51e5e

  "title": "Attribute description",

• Do we cover common SAP naming, like ABAP for Key User tools
  

  abap-file-formats/file-formats/clas/clas.json

  Line 39 in af51e5e

  "ABAP for key user tools",

• some for ABAP Language Version
  

  abap-file-formats/file-formats/clas/clas.json

  Line 42 in af51e5e

  "title": "Abap Language Version",

The part of this repo, which is worth copying will be the JSON Schemas, these can then be incorporated in other software for validation.

IMHO it will be a win for @SAP if the adoption of this is as high as possible, to make the adoption high, make it as effortless as possible i.e. a MIT license?

This is not running software, or a library, its foundational work

@SebastianWolf-SAP

https://github.com/SAP/abap-file-formats/blob/main/file-formats/clas/clas.json
uses
https://json-schema.org/draft/2020-12/schema

https://github.com/SAP/abap-file-formats/blob/main/file-formats/enho/enho.json
uses
http://json-schema.org/draft/2019-09/schema

I expect that all definitions use the same json schema version definition

value "notRelased" is not allowed,

"releaseState": "notReleased",

@schneidermic0

see "Documenting a Block of Statements" in https://help.sap.com/doc/saphelp_nw75/7.5.5/en-US/17/e98e1c1ff545cea3f95b85a0539322/content.htm?no_cache=true

see #85 (comment)

for

    TYPES:
      "! Method description
      BEGIN OF method,
        bar TYPE c LENGTH 1,
      END OF method.

I don't get any warning in the editor as suggested in the official documentation?

I think the following are missing in the INTF file definition?

• Dokumentation long texts
• Text elements
• Proxy flags?

different issue: the editor config requires no newline at end of file, editing the file via github web always adds newline at end of file

Originally posted by @larshp in #87 (comment)