docs: add section for which fields are generated or required

[adamdecaf]

What were you trying to do? Trying to generate an ACH file, but unsure which fields are required or auto populated.

What did you expect to see? Creating an ACH file without errors.

Additional Links https://moov-io.slack.com/archives/CD9J8EJKX/p1657993198153629?thread_ts=1657988088.155659&cid=CD9J8EJKX

Related Issues

See https://github.com/moov-io/ach/issues/1151

[adamdecaf]

Auto-populated Fields

• traceNumber
• batchNumber
• originatorStatusCode
• fileIDModifier

Here appears to be the minimum file required.

file.json

{
    "id": "efa5ff86-bf37-4134-a9ce-ad48ed44c4a6",
    "fileHeader": {
        "id": "efa5ff86-bf37-4134-a9ce-ad48ed44c4a6",
        "immediateDestination": "226071004",
        "immediateOrigin": "0462723539",
        "fileCreationDate": "220716",
        "fileCreationTime": "1839",
        "immediateDestinationName": "NYCB",
        "immediateOriginName": "HMBRADLEY"
    },
    "batches": [
        {
            "batchHeader": {
                "id": "76a017c6-fcc0-4c90-8043-f3b0766546d3",
                "serviceClassCode": 220,
                "companyName": "HMBradley",
                "companyIdentification": "0462723539",
                "standardEntryClassCode": "WEB",
                "companyEntryDescription": "HMBWEB",
                "effectiveEntryDate": "220716",
                "ODFIIdentification": "22607100"
            },
            "entryDetails": [
                {
                    "id": "3697e62d-ec41-4092-a7be-a2bb6cad8aa0",
                    "transactionCode": 22,
                    "RDFIIdentification": "06540013",
                    "checkDigit": "7",
                    "DFIAccountNumber": "264236473264",
                    "amount": 121598,
                    "individualName": "Zach Test",
                    "paymentTypeCode": "S"
                }
            ]
        }
    ]
}

[brendenehlers]

Hey, is this issue able to be picked up? I'm happy to help out!

[adamdecaf]

I don't believe it's been picked up. Ideally the OpenAPI spec would have all required/optional fields specified and could be the source for another document.

[brendenehlers]

I'm happy to look into the Open API spec, I'm well versed in it from another open-source project.

Would you be able to send a summary or screenshot of the slack link? I can't access and feel like I'm missing a bit of context surrounding what exactly the issue is.

[adamdecaf]

That slack link is likely lost because it's on the free plan, but the context was probably someone asking about which fields they need to provide to the HTTP api.

[brendenehlers]

Sounds good. Just to confirm, this issue involves updating the request body of the POST /file/{fileId} endpoint to require the fields mentioned in the above comment with the example? That all sound right?

[adamdecaf]

The CreateFile schema object, yes. That should be shared across all file-creating endpoints. If you could try and verify that minimum json object is all that's needed then we can be sure the docs are correct.

[brendenehlers]

Just put up a PR for this: #1410

I updated the object in the spec to only have the fields required for a successful response from the API.

In the CreateFile schema object, either batches or IATBatches, but not both, are required. I marked them both as required and mentioned in the description that it's one or the other. The required field of the spec doesn't support using oneOf, so I figured this was the best alternative.

Let me know if there's a preferred way to handle this.

[adamdecaf]

Can CreateFile have oneOf in the properties?

[brendenehlers]

Unfortunately, not in the required section.